Commenting Style

[darren78]

Hi,

I was wondering what peoples thoughts wereon commenting style. Since I have been working commercially, I have noticed a few variations. From the simple

// comment
void method()

To a little more extreme:

//************
//comment here*
//************

Personally, I prefer it when it's wrapped in the asterisks. I just think it looks neater??

Is that an acceptable style? I have only been working commercially for 2 months, so just wanted to check?

Thanks.

[laserlight]

I was wondering what peoples thoughts wereon commenting style. Since I have been working commercially, I have noticed a few variations.

Part of item 0 of C++ Coding Standards by Sutter and Alexandrescu sounds relevant here:

Don't prescribe commenting styles (except where tools extract certain styles into documentation), but do write useful comments: Write code instead of comments where possible. Don't write comments that repeat the code; they get out of sync. Do write illuminating comments that explain approach and rationale.

[kmdv]

Interesting thread. I use comments also for separating parts of code. I do know it may be considered a bad habit, but it really helps me when looking through the code (I use red color for comments). It is something like the extreme example (for separating):

////////////////////////////////////////////////////////////////////////////////
//
//  constructors & destructor
//
////////////////////////////////////////////////////////////////////////////////

The style I hate is:

/*
 *  blabla
 */

For regular comments I use simple // blabla

And do you use block comments (if at all), and how often? Because I don't use them at all (I like using them only in situations where I need to comment out a piece of code for a moment).

[laserlight]

Well, I suppose I might as well answer darren78's main question directly:

Personally, I prefer it when it's wrapped in the asterisks. I just think it looks neater??

Is that an acceptable style?

I do not think that it looks neater, but it is acceptable to me.

And do you use block comments (if at all), and how often? Because I don't use them at all (I like using them only in situations where I need to comment out a piece of code for a moment).

I use them for Doxygen comments. For commenting out a piece of code, I prefer using #if 0.

[darren78]

Interesting thread. I use comments also for separating parts of code. I do know it may be considered a bad habit, but it really helps me when looking through the code (I use red color for comments). It is something like the extreme example (for separating):

////////////////////////////////////////////////////////////////////////////////
//
//  constructors & destructor
//
////////////////////////////////////////////////////////////////////////////////

The style I hate is:

/*
 *  blabla
 */

For regular comments I use simple // blabla

And do you use block comments (if at all), and how often? Because I don't use them at all (I like using them only in situations where I need to comment out a piece of code for a moment).

Yeah, when I said it makes it look neater, I did mean for seperating code. I tend to put a brief comment about each method/function and this splits it up nicely.

[pianorain]

For commenting out a piece of code, I prefer using #if 0.

Neat idea. Since my IDE allows you to collapse sections of code that won't be compiled due to the preprocessor, that's really handy.

[sudox]

The book Practical C++ Programming covers practical commenting methods, style, and appropriate usage; despite code mistakes and some less-than-acceptable coding methods, the commenting style covered is definitely useful information.