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:​
Xbase++: 
// returns normalized value for distance
RETURN( xCalc / 12 + 2 )
// write this:
RETURN( NormalizeValueForDistance( xCalc ) )

But write comments to warn for consequences such as:
Xbase++: 
/* Do not remove upper is req. to support case insensitivity in Interface
 */
Name := Upper(cName)
​

Hints:​

  • Write comments which describe your decision why you did something that way!
  • Write TODO comments if you want to add a code/feature or edge case implementation later.
  • Your comments must be more informative than the code!
  • Your comments should provide intent or rationale!
  • Fix bad code, don’t write comments!