Learning Center
Plans & pricing Sign in
Sign Out

A PASSING COMMENT Prepared by Hyeongmok Lee In this chapter



             Prepared by Hyeongmok Lee
               In this chapter:
   What are comments used for?
   How many comments are required?
   How to write effective comments
        What is a Code Comment?
   Semantically, a comment is the difference
    between a dingy dirt track and a well-lit highway
   Comments are aimed at the human reader, not
    the computer
   Code comments are not the only documentation
    that you should put in your code
     What Do Comments Look Like?
   C comments come in blocks between /* and */
    and can span any number of lines.
   C++, C99, C#, and Java add the single line
    comment that follows //
   Others provide similar block and line comment
    facilities, but with different syntaxes
           How Many Comments?
   Learn to write enough comments, and no more,
    Favor quality, not quantity
   Spend your time writing code that doesn't need
    to be propped up by tons of comments
    What Goes Inside Our Comments?
   Good comments explain why, not how

     /* update WidgetList structure from
    GlbWLRegistry */

    /* cache widget information for later */
    What Goes Inside Our Comments?
   Don't Describe the Code

    ++i; // increment i
    What Goes Inside Our Comments?
   Honor the golden rule: One fact – one source.
    Don't duplicate code in a comment
   When you find yourself writing dense comments
    to explain your code, step back. Is there a bigger
    problem to solve?
   Think about what you're writing in a comment;
    don't type without using your brain. Read it back
    again in the context of the code. Does it contain
    the right information?
                     In Practice
for (int i = 0; i <; ++i)

// Iterate over all widgets in the widget list
for (int i = 0; i <; ++i)
   // print out this widget
                    In Practice
for (int i = 0; i < widgets.size(); ++i)
         A Comment on Aesthetics
   All commenting should be clear and consistent.
    Choose a specific way to lay out your comments,
    and use it throughout
        A Comment on Aesthetics
   Clear Block Comments

/* This is much more readable
/* as a block comment in the midst
/* of a whole pile of code

a comment that might
    span a few line but without
any margin character.
        A Comment on Aesthetics
   Indenting Comments

void strangeCommentStyle()
   for (int n = 0; n < JUST_ENOUGH_TIMES; ++n)
// This is a meaningful comment about the next line.
// But frankly, it's confusing the pants off of me.
        A Comment on Aesthetics
   End-of-Line Comments

class HandyExample
      … some nice public stuff …
      int appleCount;            // End-of-line comments:
      bool isFatherADustman;     // Make them stand out
      int favoriteNumber;        // from the code
        A Comment on Aesthetics
   Comments are part of the code narrative. Use
    them in a way that reads naturally
   Choose a Low-Maintenance Style
          A Comment on Aesthetics
   Breakwaters

/* class foo implementation
            A Comment on Aesthetics
   Flags
// XXX

   File Header Comments
          Working with Comments
   Comments should live in the present, not the
    past. Don't describe things that have changed, or
    tell what something used to do
   When you alter code, maintain any comments
    around it
    Good programmers...             Bad programmers...
   Try to write a few really      Can't tell the difference
    good comments                   between good and bad
   Write comments explaining
    why                            Write comments explaining
   Concentrate on writing
    good code rather than a        Don't mind if comments
    plethora of comments            only make sense to
   Write helpful comments
    that make sense                Bolster bad code with
                                    many comments
                                   Fill their source files with
                                    redundant information
                                    (revision history, etc.)
Thank you

To top