Dreaded Code Style Argument

Hey fellas,

I was just having a look at this article on flipcode.com about coding style.

here is the link:
http://www.flipcode.com/articles/art...ingstyle.shtml

Everything the guy does seems sound to me, except for a couple of things.
He's extremely comment happy it seems to me. I can see the infinite advantages in well documented code, however I would much prefer to read/write a seperate documentation to accompany the code. This guy's code gets bloated VERY quickly.

Secondly, the opening curly bracket. A lot of people seem to use this style (same line) but to me it seems much nicer to have it on the next line, what's the argument for using this same-line style?

Lastly I have an actual question, I'm sure I've read about this before, but what does a const return type do for a function? Anything exciting?

Its a good thing to be comment happy. Just think if you have a program hat you created a few months ago, and you decide to update. If you didn't have comments then you would not have a clue whats happening. belive me I have done it and now I comment just as much as any guy.
The open brace thing is just a matter of style with C++ there is no right way of doing things. I personally agree with you about having the brace on the next line. The only time I don't is when im doing a quick one line function.
The const return type I have only come across when using pointers it makes sure that the pointer can't be altered in any way. In other word if it points to an int then it will always do so. Just the same as if you place it after the function name. Im sure you have heard this before but its good programming practice.

Having the opening brace on the same line is an old fashioned style. It arose in the days when we all used character mode terminals which only displayed 24 lines of text. You could see more of the code on the screen using this style.

Many people still hang on to this style despite studies which show Allman format has the greatest readability and fewest "first glance" errors.

Despite those "studies" I prefer to have the opening bracket on the same line. I don't know who "Allman" is and frankly, I don't really care what some people think is readable and what not. :) To me, having the opening bracket on the same line is a lot easier to read.

As for this piece of code found in Hybrid's link....

Code:

public: /** * Get the speed of the car * * @return speed in miles per hour. */ const float getSpeed(); /** * Set the speed of the car * * @param pSpeed new speed of the car. */ void setSpeed(const float pSpeed);

...

I think it's definetly not something I could "show my mama". It's overloaded with comments. It's like not finding the wood because of all the trees.

I try not to use any comments "in" the code unless its a comment about an entire code-block. I prefer to have comments about a single function like the above ones behind the function, starting at column 60 if possible.

btw, how do you wrap long parameterlists ? Like this ?

Code:

// use glu to build mipmaps gluBuild2DMipmaps( GL_TEXTURE_2D, oImage.iChannelCount, // must be 3 or 4, 4 for RGBA mode oImage.iSizeX, oImage.iSizeY, iTexMode, // rgb or rgba textures GL_UNSIGNED_BYTE, // subpixel datatype oImage.pbData );

Thats how I normally do it and it's analog to the way I use the curly brackets.

what does a const return type do for a function? Anything exciting?

If you do something like this, I don't think it has any meaning:

Code:

const int func(void) { const int sum = 10; return sum; }

...because you are passing by value in the return statement, and therefore a copy of sum is made and the copy is returned. Since a copy cannot modify the original, the compiler doesn't care what you do with the return value. (I don't know how the original being destroyed when the function returns fits into the story--it might be the whole story.)

But, if you have something like this:

const int* func(void)

then you aren't allowed to do this:

int* pint = func();

because you might try this:

*pint = another_value;

and that would violate the constantness of the int "pointed to by the pointer" that the function returned--which is extremely exciting stuff.

Using const for a copied return type is useless.

Those comments such as these, though:

Code:

public: /** * Get the speed of the car * * @return speed in miles per hour. */ const float getSpeed(); /** * Set the speed of the car * * @param pSpeed new speed of the car. */ void setSpeed(const float pSpeed);

can be useful; there are a lot of automatic documentation-generation programs that can make HTML or some other form of documentation from comments like these; I imagine that may be his purpose. I see this a lot on projects I work on; it makes maintaining the documentation, especially in the presence of multiple developers making changes, much easier.

I do not comment my code as heavily as he does. I remember I had a CS professor who once said "If your code needs a lot of comments to understand it, then delete it and write clearer code."

I also use the "old style" of open braces on the same line, just because I've been programming for ages and that's just how I've always done things. Once you're used to it, it's as easy to read.

As Cat said, especially with the '@' character and the format of those particular lines, it is for the automatic documentation tools. His code inside the functions themselves I disagree with. If you have code which is complex, or subtle, then it definitely should be well commented. Comments like this:

// Create a pointer to an int storing age.
int* pAge;

Are useless (in my opinion), however. First, the line of code says exactly the same thing that the comment does, and if you changed something (type, etc.) then the comment would go from useless to detrimental unless you made sure to update it as well. If there are fewer comments (placed as needed in complex code), then they are much more likely to be updated when something changes.

I played around a bit with doxygen, the documentation program he uses -- it's quite good, actually, I plan to use it on any large project or anywhere I think I will be reusing code.