• Write comments at the level of the code's intent

• Focus your documentation efforts on the code itself

• Focus your paragraph comments on the why rather than the how

   // If account flag is zero
   if (accountFlag == 0) ...
   
   vs.
   
   // Establish a new Account
   if (accountFlag == 0) ...

• Use comments to prepare the reader for what is to follow, scanning only the comments should be enough for the reader of what the code does and where to look for a specific activity of interest.

• Make every comment count, don't write comments for the sake of writing comments, too many comments obscure the code, put extra effort into making code more readable rather than into comments

• Document surprises and gotcha's, if you used a tricky technique, document it. If you ran into a surprising solution that was nevertheless correct, document it.

• Document performance work-arounds, show what the normal straight forward code should be then explain briefly why the tricky approach gives a performance win and thus is justified.

       // use right shift to divide by two, cuts parent loop time by 75%
       elementList[ element ] = elementList[ element ] >> 1;

• Avoid abbreviations

• Differentiate between major and minor comments

• Comment anything that gets around an error or an undocumented feature in a language or programming environment

• Justify any violations of good programming style

• Don't comment tricky code, rewrite it

-- ShawnDB - 16 Jun 2008
to top