code style topic

code style topic

Postby nido » 20 Mar 2014, 00:00

In this topic I would like to specifically address the layout of the code, rather then the functionality itself.

Reason for creating this thread is reading about the bad indentation in the source tree. I would like to make a suggestion in order to better the situation without putting considerable manual effort into it. To this effect, I propose the following:

- Someone links me to a definition of our code style (layout), and i'll go find a formatter that could make all code be as such, or

- We decide on a code style (in respect to this project, the best choice would be one of the arch-styles, kernel, gnu, k&r or bsd) and we do the same as above, or

- we let clang-formatter loose and have it decide what would be a consistent style and at least have the code consistently formatted (possibly whilst having a holy war over what shall be the One True Bracestyle)


I'd also like to propose to have this done in one grand sweep of all code files, by a committer identified as 'formatter', or something similar indicating this was not a "real" change.

I would be interested to hear your opinions.
nido
 
Posts: 57
Joined: 07 Mar 2014, 00:47

Re: code style topic

Postby charlie » 20 Mar 2014, 09:26

Code style is one of those things people (including myself) obsess over but actually matters very little. Prettifying code is basically a way to procrastinate on doing the important tasks.

As long as code is well documented (and said documentation kept up to date) and variables/classes named clearly and sensibly, the actual "style" off the code is nigh irrelevant.
Free Gamer - it's the dogz
Vexi - web UI platform
User avatar
charlie
Global Moderator
 
Posts: 2131
Joined: 02 Dec 2009, 11:56
Location: Manchester, UK

Re: code style topic

Postby Bertram » 20 Mar 2014, 09:54

Hi there,

charlie {l Wrote}:Code style is one of those things people (including myself) obsess over but actually matters very little. Prettifying code is basically a way to procrastinate on doing the important tasks.

As long as code is well documented (and said documentation kept up to date) and variables/classes named clearly and sensibly, the actual "style" off the code is nigh irrelevant.

Well, I'll be straight. That's utterly wrong, and I could say that only from personal experience on my OD's latest changes. I don't know what made you think this, but working with people that just don't care about the common code style is something unbearable, and not only for me, this also from personal experience with a few other teams.

Having code badly indented, baldy formed, without hint about variables use, ill-named members variables and so on, just permits even more mistakes.
It's just like if you said that when reading a book, the grammar, syntax, and the overall book paragraphs format wasn't important if the text is interesting.
This doesn't make the book unreadable if you really want to, but it's really hurting, right?
So, it's no procrastination at all, it's a standard code curation measure.

I do agree about the fact that the documentation is important, though.

As for Nido's point:
Let me request once again to not apply a code style script right now. I'm in process of reviewing the whole code and apply the code conventions at the same time. As this will permit me to get to know it sufficiently to be more at ease for the next additions. Just give me two or three more weeks. Afterward, I'm ok with applying something. :)

Best regards,
Last edited by Bertram on 20 Mar 2014, 15:08, edited 1 time in total.
User avatar
Bertram
VT Moderator
 
Posts: 1652
Joined: 09 Nov 2012, 12:26

Re: code style topic

Postby andrewj » 20 Mar 2014, 10:01

Code style does matter. For example, when people put a '{' (in C or C++ code) at the end of a line, I find such code a lot harder to read or even browse through. When typing code in, I would automatically press ENTER first and then the '{' of a new block, and conforming to the other way would be painful.

I think that the people who spend the most time on the code, often just two or three people -- they are the ones who get to choose the coding style, and everyone else has to lump it (put up with it).
User avatar
andrewj
 
Posts: 194
Joined: 15 Dec 2009, 16:32
Location: Tasmania

Re: code style topic

Postby charlie » 20 Mar 2014, 14:35

> Badly indented

Of course, that needs correcting. That's not even style. That's just sensible.

> { at the end of a line

So you find one way easier to read. Others find the other. As long as you don't mix and match in a file, it won't matter too much. You're making a big deal out of something small there.
Free Gamer - it's the dogz
Vexi - web UI platform
User avatar
charlie
Global Moderator
 
Posts: 2131
Joined: 02 Dec 2009, 11:56
Location: Manchester, UK

Re: code style topic

Postby Bertram » 20 Mar 2014, 15:07

Of course, that needs correcting. That's not even style. That's just sensible.

I think that was one of nido's point when opening this topic.

But hopefully, we'll be through this soon enough. :)
User avatar
Bertram
VT Moderator
 
Posts: 1652
Joined: 09 Nov 2012, 12:26

Re: code style topic

Postby nido » 20 Mar 2014, 23:08

Code style is one of those things people (including myself) obsess over but actually matters very little. Prettifying code is basically a way to procrastinate on doing the important tasks.

It's just like if you said that when reading a book, the grammar, syntax, and the overall book paragraphs format wasn't important if the text is interesting.

Of course, that needs correcting. That's not even style. That's just sensible.

I think that was one of nido's point when opening this topic.

> { at the end of a line

The common caviat of codestyle is that it is not so important which code style is used, as long as there is a codestyle. This incudes indentation, brace style, spacing between words, arguments, at which side the * goes in a pointer definition and so on. A consistent style will make a codebase more readable, even if it is different from your preferred choice.

The proposal also explicitly mentions the use of a formatter tool. The whole process would take me about an hour, allowing time for problems trying to commit stuff written by "formatter" rather then "nido". Not much procastination in my opinion for a better readable source tree.

Let me request once again to not apply a code style script right now. I'm in process of reviewing the whole code and apply the code conventions at the same time.


I apologise for the reiteration of this proposal. I was unaware of the previous incantation and ask your forgiveness. I was under the impression the bad code style was a burden to your progress, which was why I made the suggestion sooner rather then later.

Assuming we do have a consensus on applying a formatter to get our code in line, I suggest we consider which code style to use for opendungeons. My personal preference would go to one of the four named earlier because i have a formatter tool which i know the switches for how to set it. If someone has a strong preference for some reason such as andrewj mentioned, I would like to hear it.
nido
 
Posts: 57
Joined: 07 Mar 2014, 00:47

Re: code style topic

Postby Bertram » 21 Mar 2014, 02:21

Hi Nido, :)

I apologise for the reiteration of this proposal. I was unaware of the previous incantation and ask your forgiveness. I was under the impression the bad code style was a burden to your progress, which was why I made the suggestion sooner rather then later.

Np at all. ;)

Assuming we do have a consensus on applying a formatter to get our code in line, I suggest we consider which code style to use for opendungeons. My personal preference would go to one of the four named earlier because i have a formatter tool which i know the switches for how to set it. If someone has a strong preference for some reason such as andrewj mentioned, I would like to hear it.

I'd request 4 spaces indentation, and a m before member variables: Eg: mMember; so we can distingish them easily from the rest.
I also like adding something like an underscore for private members and functions since it helps when debugging, but it's not very important.

Best regards,
User avatar
Bertram
VT Moderator
 
Posts: 1652
Joined: 09 Nov 2012, 12:26

Re: code style topic

Postby nido » 21 Mar 2014, 23:30

If I may ask a question, aren't member variables already distinguishable from local variables in the sense that you access them via this->, and distinguishable from member functions by not being used with parentheses? My experience in c++ is limited so I am unsure about this.

As for an indicator for private members, that may be adventurous because one cannot syntactically differentiate between private and public members. I would vote for a 'p' rather then an underscore though, as these names are reserved. To quote the last draft on c++11, n3690 (not gonna spend money on getting the latest):

17.6.4.3.2 Global names
Certain sets of names and function signatures are always reserved to the implementation:
—Each name that contains a double underscore or begins with an underscore followed by an uppercase letter (2.12) is reserved to the implementation for any use.
—Each name that begins with an underscore is reserved to the implementation for use as a name in the global namespace.

I think this does include names within user classes, but i may be mistaken
nido
 
Posts: 57
Joined: 07 Mar 2014, 00:47

Re: code style topic

Postby Bertram » 25 Mar 2014, 09:42

Hi nido, :)

If I may ask a question, aren't member variables already distinguishable from local variables in the sense that you access them via this->, and distinguishable from member functions by not being used with parentheses? My experience in c++ is limited so I am unsure about this.

Member variables aren't distinguishable in term of pure code readability. I'm not talking about pure C++ here, but about the guy that has to go read the file and understand what happens there and has to read a diff to try to understand a change.

Of course, I could add 'this->' and wait for my IDE to display the member list, but I wouldn't have to do that if the members are clearly tagged as ones. This is less error-prone and quicker for me in term of readability, at least IMO.

As for an indicator for private members, that may be adventurous because one cannot syntactically differentiate between private and public members. I would vote for a 'p' rather then an underscore though, as these names are reserved. To quote the last draft on c++11, n3690 (not gonna spend money on getting the latest):

Yeah, that's a valid point.
Last edited by Bertram on 28 Mar 2014, 08:55, edited 1 time in total.
User avatar
Bertram
VT Moderator
 
Posts: 1652
Joined: 09 Nov 2012, 12:26

Re: code style topic

Postby nido » 27 Mar 2014, 23:57

Bertram {l Wrote}:Of course, I could add 'this->' and wait for my IDE to display the member list, but I wouldn't have to do that if the members are clearly tagged as ones. This is less-prone and quicker for me in term of readability, at least IMO.

We seem to have different experiences with writing code. Still, whilst I personally still prefer otherwise I see no problem in using m convention within opendungeons since this convention seems to be implemented in the code already.

However, we are now discussing parts which are not easily adressable with an automated formatter.

To that end, I suggest we discuss what should be OD's One True Bracestyle. If I am correct the current suggestions are '}' on new lines and four spaces indentation. May I suggest we go for allman style and put '{'s on their respective own lines as well? http://en.wikipedia.org/wiki/Indent_style#Allman_style . Possibly with the exclusion of '} else {'
nido
 
Posts: 57
Joined: 07 Mar 2014, 00:47

Re: code style topic

Postby Bertram » 28 Mar 2014, 09:00

We seem to have different experiences with writing code. Still, whilst I personally still prefer otherwise I see no problem in using m convention within opendungeons since this convention seems to be implemented in the code already.

Great.

To that end, I suggest we discuss what should be OD's One True Bracestyle. If I am correct the current suggestions are '}' on new lines and four spaces indentation. May I suggest we go for allman style and put '{'s on their respective own lines as well? http://en.wikipedia.org/wiki/Indent_style#Allman_style . Possibly with the exclusion of '} else {'


The Allman style is already what's being done mostly, so I have got no problem with that. :)
User avatar
Bertram
VT Moderator
 
Posts: 1652
Joined: 09 Nov 2012, 12:26

Who is online

Users browsing this forum: No registered users and 1 guest