• Comments should tell the input, output, preconditions, invariants, motivation. Don't worry about how, but concentrate on defining what the code operates on correctly, and the why. (E.g., my version of the long comment below would be mostly definition; Shawn's was procedural.) -- JackSnoeyink - 19 Jun 2008

• Design routines in pseudocode, convert the pseudo code to comments, fill in the actual code to make each line of pseudo-code work correctly, the pseudo-code approach helps you to design the routine correctly before you even start programming. And then the comments become summary or intent comments reminding you of the original solution.

• A conflict between code and it's associated comment indicates a bug (probably in both), refactor the code and it's associated comment to be correct

• in C++ (and Java), use '//' for single line comments (and endline comments), use '/*...*/' for multi-line comments (and embedded comments)

Single-Line Example:
      // Compute 1-ring of this vertex

End-Line example:
      bResult = BuildOneRing( currVertex, newVertex );  // Compute 1-ring for this vertex

Multi-Line Example:
      /*-------------------------------------------------------------------------
         Name:  BuildOneRing()
         Desc:  Builds the 1-ring for the current vertex
         Note:  (JSS) The 1-ring of a vertex is the list of 
                (the triangles? the incident edges? the neighboring vertices?) 
                in CCW order around the vertex so that any two adjacent items have 
                a triangle between them.  
                If the order is circular, we have a closed loop and 
                an interior vertex. If not, then the current vertex and 
                first and last vertices of the list are all boundary vertices. 
                The vertex must be manifold for the order to be established, 
                otherwise the vertex is called complex (or malformed). 

                (SDB) We compute the one ring by computing predecessor 
                and successor vertices for each non-indicent edge in
                the incident triangle list, then starting at a vertex and
                walking CCW using the predecessor list to find the leftmost edge.
                If the leftmost edge is the same as our starting edge, 
                we have a closed loop, a valid 1-ring, and are on an interior
                vertex of the mesh.
                Otherwise, we start from the leftmost edge, and walk CW using
                the successor list to find the rightmost edge.  If the chain
                from leftmost to rightmost includes all neighboring vertices, we 
                have an open chain, a valid 1-ring, and are on an exterior vertex
                of the mesh.
                Otherwise, we have a complex (or malformed vertex).                 
      ----------------------------------------------*/

Embedded Example:

      /*virtual*/ void SPreader::compute_bounds()
      { 
      }

• Make comments as you code, instead of waiting to the end of the project to comment, you almost always run out of time to do the right thing

• Performance goals are not a good reason to not comment, if necessary, you can always write a post-process tool to strip out comments before building

• Too many comments are as bad as too few. Find an efficient middle ground

• As an aside, an IBM study found that 1 comment line per 10 lines of code was most optimal for clarity. Fewer comments than this resulted in hard to understand code, More comments than this also resulted in increased programmer confusion in understanding the code.

• Use a commenting style that is easy to maintain, IE avoid unnecessary ornamentation in comment sections

    // Harder to maintain

    /*--------------------------------------------------------------------------------
    - FILE:  spreader.h                                                              -
    -                                                                                -
    - CONTENTS:  Streaming Pointer Reader Interface                                  -
    - ...                                                                            -
    --------------------------------------------------------------------------------*/

    // Slightly easier but still requires exta work

    //--------------------------------------------------------------------------------
    // FILE:  spreader.h                                                             
    //                                                                               
    // CONTENTS:  Streaming Pointer Reader Interface                                 
    // ...
    //--------------------------------------------------------------------------------


    // Easiest to maintain

    /*--------------------------------------------------------------------------------
       FILE:  spreader.h
       CONTENTS:  Streaming Pointer Reader Interface
       ...
    --------------------------------------------------------------------------------*/
      

-- ShawnDB - 16 Jun 2008
to top