| ... |
... |
@@ -23,14 +23,14 @@ |
| 23 |
23 |
* Prescriptive comments |
| 24 |
24 |
* Diary comments |
| 25 |
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. |
|
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 |
30 |
* Commented code |
| 31 |
31 |
* HTML comments |
| 32 |
|
-* Non-local information |
|
32 |
+* Non-local information that is not directly related to the immediate code. |
| 33 |
33 |
* Too much information |
| 34 |
34 |
* Unclear context |
| 35 |
|
-* Function header |
|
35 |
+* Function headers, which are comments that precede a function and describe what the function does, its parameters, return values, etc. |
| 36 |
36 |
* Javadocs in non-public API's |
