Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | #### General Guidelines | ||
| 2 | |||
| 3 | * 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. | ||
| 4 | * Comments can lie because they are hard to maintain. When the code changes, the comments are usually forgotten or ignored. | ||
| 5 | * Comments are no substitute for bad code. | ||
| 6 | |||
| 7 | ### Good Comments | ||
| 8 | |||
| 9 | * Legal comments: Copyrights, Authors. It's best to reference a standard license or external document so as not to deface the code. | ||
| 10 | * Informative comments | ||
| 11 | * Statement of intent | ||
| 12 | * Clarifications | ||
| 13 | * Warnings of consequences | ||
| 14 | * TODO comments | ||
| 15 | * Reinforcement of code that is otherwise perceived as unimportant | ||
| 16 | * Javadocs in public API's. | ||
| 17 | |||
| 18 | ### Bad Comments | ||
| 19 | |||
| 20 | * Whispers | ||
| 21 | * Redundant comments | ||
| 22 | * Misleading comments | ||
| 23 | * Prescriptive comments | ||
| 24 | * Diary comments | ||
| 25 | * Chatter | ||
| 26 | * Position identifier, e.g. "// End of function" | ||
| 27 | * 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. | ||
| 28 | * 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. | ||
| 29 | * 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. | ||
| 30 | * Commented code | ||
| 31 | * HTML comments | ||
| 32 | * Non-local information that is not directly related to the immediate code. | ||
| 33 | * Too much information | ||
| 34 | * Unclear context | ||
| 35 | * Function headers, which are comments that precede a function and describe what the function does, its parameters, return values, etc. | ||
| 36 | * Javadocs in non-public API's |