Commenting Style

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

Code:

---


// comment
void method()

---

To a little more extreme:

Code:

---

//************
//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.

Quote:

---

Originally Posted by darren78

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:

Quote:

---

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.

---

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):

Code:

---

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

---

The style I hate is:

Code:

---

/*
 *  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).

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

Quote:

---

Originally Posted by darren78

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.

Quote:

---

Originally Posted by kmdv

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.

Quote:

---

Originally Posted by 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):

Code:

---

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

---

The style I hate is:

Code:

---

/*
 *  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.

Quote:

---

Originally Posted by laserlight

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.

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.