General Tips on Comments
- 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
Revision: r1.1 - 19 Jun 2008 - 11:47 - Main.guest