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 ) )
Write comments to warn for consequences such as:
/* Do not remove upper is req. to support case insensitivity in Interface */ cName := Upper(cName)
#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.
- Your comments must be more informative than the code!
- Your comments should provide intent or rationale!
- Fix bad code, don’t write comments!