Comments

General Guidelines

• Code should speak for itself. It is better to explain things in and through the code. Comments are at best a necessary evil when you can't express something in code.
• Comments can lie because they are hard to maintain. When the code changes, the comments are usually forgotten or ignored.
• Comments are no substitute for bad code.

Good Comments

• Legal comments: Copyrights, Authors. It's best to reference a standard license or external document so as not to deface the code.
• Informative comments
• Statement of intent
• Clarifications
• Warnings of consequences
• TODO comments
• Reinforcement of code that is otherwise perceived as unimportant
• Javadocs in public API's.

Bad Comments

• Whispers
• Redundant comments
• Misleading comments
• Prescriptive comments
• Diary comments
• Chatter
• Position identifier, e.g. "// End of function"
• Comments after closing parentheses, originally intended to be useful for long functions by highlighting sections, e.g. "} // End of for loop". However, they should be avoided and the function should be shortened.
• Attributions: Something used to keep track of who wrote or modified a piece of code. Usually handled automatically by a source code control system like Git.
• Asides: An off-topic comment in the source code, which is usually to be avoided because it distracts from the main purpose of the code, making it harder to understand.
• Commented code
• HTML comments
• Non-local information that is not directly related to the immediate code.
• Too much information
• Unclear context
• Function headers, which are comments that precede a function and describe what the function does, its parameters, return values, etc.
• Javadocs in non-public API's