Rules

Avoid the need for comments, write clear, readable and self describing code instead


Comments never describe the code and its syntax

Use comments to compensate for your failure to express yourself in code properly.


Do not write informative comments such as:


// returns normalized value for distance
RETURN( xCalc / 12 + 2 )
// write this:
RETURN( NormalizeValueForDistance( xCalc ) )
CPP

Write comments to warn for consequences such as:

/* Do not remove upper is req. to support case insensitivity in Interface
 */
cName := Upper(cName)

CPP

#6 Write comments which describe your decision why you did something that way!

#7 Write TODO comments if you want to add a code/feature or edge case implementation later.

.

Remember

  • Your comments must be more informative than the code!
  • Your comments should provide intent or rationale!
  • Fix bad code, don’t write comments!