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
    23,641
    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.
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    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
    684
    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
    23,641
    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 Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    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