Documents
Resources
Learning Center
Upload
Plans & pricing Sign in
Sign Out

A PASSING COMMENT Prepared by Hyeongmok Lee In this chapter

VIEWS: 20 PAGES: 21

									A PASSING COMMENT




             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


    e.g.)
     /* update WidgetList structure from
    GlbWLRegistry */


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


    e.g.)
    ++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 < wlst.sz(); ++i)
k(wlst[i]);


// Iterate over all widgets in the widget list
for (int i = 0; i < wlst.sz(); ++i)
{
   // print out this widget
   k(wlst[i]);
}
                    In Practice
for (int i = 0; i < widgets.size(); ++i)
{
   printwidget(widgets[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.
      doSomethingMeaningful(n);
// But frankly, it's confusing the pants off of me.
      anotherUsefulOperation(n);
   }
}
        A Comment on Aesthetics
   End-of-Line Comments

class HandyExample
{
   public:
      … some nice public stuff …
   private:
      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
// FIXME
// TODO


   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
                                    comments
   Write comments explaining
    why                            Write comments explaining
                                    how
   Concentrate on writing
    good code rather than a        Don't mind if comments
    plethora of comments            only make sense to
                                    themselves
   Write helpful comments
    that make sense                Bolster bad code with
                                    many comments
                                   Fill their source files with
                                    redundant information
                                    (revision history, etc.)
Thank you
Q&A

								
To top