Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 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 | * Do not use a comment if it can be replaced by a descriptive function or variable. | ||
| 27 | * Position identifier | ||
| 28 | * Comments after closing parentheses to emphasize sections may make sense for long functions. They should be avoided and the function abbreviated. | ||
| 29 | * Attributions and asides are unnecessary because source control systems take over this job. | ||
| 30 | * Commented code | ||
| 31 | * HTML comments | ||
| 32 | * Non-local information | ||
| 33 | * Too much information | ||
| 34 | * Unclear context | ||
| 35 | * Function header | ||
| 36 | * Javadocs in non-public API's |