Unravel the art of writing code comments that enhance readability and maintainability. Discover how to strike the perfect balance between too much and too little, and learn to craft comments that illuminate rather than obscure your code's intent.
Rules to achieve a happy medium
Comments should not duplicate the code
- Good comments do not excuse unclear code.
- If you can’t write a clear comment, there may be a problem with the code. Rule 4: Comments should dispel confusion, not cause it. Rule 5: Explain unidiomatic code in comments. Rule 6: Provide links to the original source of copied code.
- Include links to external references where they will be most helpful. Rule 8: Add comments when fixing bugs. Rule 9: Use comments to mark incomplete implementations.
Explain unidiomatic code in comments
Without the comment, someone might “simplify” the code or view it as a mysterious but essential incantation. Save future readers time and anxiety by writing down why the code is needed.
- A judgment call needs to be made as to whether code requires explanation.
Include links to external references where they will be most helpful
Links to standards and other documentation can help readers understand the problem your code is solving.
Use comments to mark incomplete implementations
Sometimes it’s necessary to check in code even though it has known limitations
- TODO comment: // TODO(hal): We are making the decimal separator be a period, // regardless of the locale of the phone.
- Add an issue to your tracker, and reference the issue in your comment
If you can’t write a clear comment, there may be a problem with the code
Debugging is twice as hard as writing the code in the first place
- Warning readers away from your code is like turning on your car’s hazard lights
- Instead, rewrite the code to something you understand well enough to explain or, better yet, that is straightforward
Conclusion
Comments don’t excuse or fix bad code, they complement good code by providing a different type of information
Comments should dispel confusion, not cause it
If your comment causes confusion instead of dispelling it, remove it.
- This rule applies to bad comments as well as good ones
- Peter Samson refused to add comments to his source code explaining what he was doing, leading to confusion until someone figured out it was an abbreviation for Rest In Peace Johann Sebastian Bach.
Provide links to the original source of copied code.
Including a reference to the source enables future readers to get the full context, such as: what problem was being solved, who provided the code, why the solution is recommended, what commenters thought of it, and how it can be improved.
Comments should not duplicate the code
Comments that add no information have negative value because they: add visual clutter
- Take time to write and read
- Can become out-of-date
- Policies requiring comments for every line of code have been rightly ridiculed on Reddit
Good comments do not excuse unclear code
Don’t provide information that should have been in the code.
- The need for comments could be eliminated with better variable naming: private static Node getBestChildNode(Node node) { Node bestNode; Node currentNode: node.getChildren()) // best child node candidate
- if (bestNode == null || utility(currentNode) > utility(bestNode)) { – bestNode = currentNode; – currentNode = bestNode + (node currentNode + bestNode) / (n) / n; – return bestNode
Add comments when fixing bugs
Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs.
- Not only does the comment help the reader understand the code in the current and referenced methods, it is helpful for determining whether the code is still needed and how to test it.
