Comments
Write the least possible comments
Prefer coding to commenting
The code should document itself as most as possible
Many and long comments are code smell
Comments Should Be
Meaningful
Necessary
Readable
Bad Comments
„Commented out” code - Remove it, find it in the version control system
Separators, markers
Redundant
Misleading
Out-of-date
Obvious
Unnecessary
Funny
Closing brace comment
Attributes - author, date, issue number, etc.
Non-English
Too many HTML markers
Historical
Prone to copy-paste error
Good Comments
TODO comments
Warnings - e.g. "Not threadsafe"
Limitations - e.g. "It works only with a sorted list"
Javadoc comment to public API - for high level service methods
Comment empty blocks
Less is more.
Example: Bad: Comments
Example: Good: Javadoc comment
Last updated