Commenting Style

This is a discussion on Commenting Style within the C++ Programming forums, part of the General Programming Boards category; Hi, I was wondering what peoples thoughts wereon commenting style. Since I have been working commercially, I have noticed a ...

  1. #1
    Registered User
    Join Date
    Feb 2009
    Posts
    329

    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.

  2. #2
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,910
    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:
    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.
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  3. #3
    Registered User
    Join Date
    Aug 2010
    Location
    Poland
    Posts
    682
    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).
    Last edited by kmdv; 11-18-2010 at 09:17 AM.

  4. #4
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,910
    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.
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  5. #5
    Registered User
    Join Date
    Feb 2009
    Posts
    329
    Quote Originally Posted by kmdv View Post
    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.

  6. #6
    Anti-Poster
    Join Date
    Feb 2002
    Posts
    1,399
    Quote Originally Posted by laserlight View Post
    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.
    If I did your homework for you, then you might pass your class without learning how to write a program like this. Then you might graduate and get your degree without learning how to write a program like this. You might become a professional programmer without knowing how to write a program like this. Someday you might work on a project with me without knowing how to write a program like this. Then I would have to do you serious bodily harm. - Jack Klein

  7. #7
    Registered User
    Join Date
    Nov 2010
    Posts
    13
    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.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. WM_CAPTION causing CreateWindowEx() to fail.
    By Necrofear in forum Windows Programming
    Replies: 8
    Last Post: 04-06-2007, 08:23 AM
  2. Button handler
    By Nephiroth in forum Windows Programming
    Replies: 8
    Last Post: 03-12-2006, 05:23 AM
  3. Commenting Style Preference
    By techrolla in forum C++ Programming
    Replies: 16
    Last Post: 12-10-2004, 10:15 AM
  4. WS_EX_COMPOSITED style (double buffering) problems
    By JasonD in forum Windows Programming
    Replies: 2
    Last Post: 10-12-2004, 11:21 AM
  5. Tab Controls - API
    By -KEN- in forum Windows Programming
    Replies: 7
    Last Post: 06-02-2002, 09:44 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21