Writing Effective Code Comments: Best Practices and Philosophy

To write comments, or not to write comments, that is the question.

In the world of software design, John Ousterhout’s “A Philosophy of Software Design” and Robert C. Martin’s (Uncle Bob’s) “Clean Code” offer different lenses through which to view code commenting. Ousterhout emphasizes creating inherently understandable software designs that minimize the need for comments, while Uncle Bob, in “Clean Code,” suggests that the best comment is the one you felt wasn’t needed. Both emphasize that comments should not compensate for bad code. With that stage set, let’s delve deeper into Ousterhout’s insights on effective commenting.

Characteristics of Effective Comments by Ousterhout:

1. Explain the “What” and “Why” Not the “How”: Good comments clarify what a piece of code does and why it’s necessary, offering context and intent. The reasoning, whether it’s a specific algorithm choice or a workaround, provides invaluable insights. While the mechanics of “how” should be evident in well-written code, comments are best used to shed light on non-obvious decisions or complex rationales.
2. Provide Insights that Are Not Obvious: A good comment offers information that’s not immediately discernible from the code itself. It shouldn’t state the obvious.
3. Avoid Redundancy: Comments should not restate what the code is already making clear. Redundant comments can be more of a distraction than a help.
4. Comments as a Warning: Comments can act as a warning sign, indicating complex or tricky parts of the code where extra attention might be needed.
5. To-Do Comments: If there are future actions or improvements planned for a particular section of the code, comments can indicate this with “TODO” notes, but these should be used judiciously.
6. Decision Rationale: If there were multiple ways to implement a particular piece of functionality, and a specific approach was chosen for a particular reason, that reasoning can be documented in a comment.
7. High-Level Overview: At the beginning of a module or a class, comments can offer a high-level overview of its purpose and behavior, providing context for someone diving into the code.
8. Use Sparingly: Comments should not be overused. If everything is commented extensively, it can make the code harder to read. The goal is to achieve a balance where the code is primarily self-explanatory, supplemented by comments where necessary.
9. Keep Them Updated: Outdated comments that don’t match the code are worse than no comments at all. They can mislead and confuse readers. When updating code, it’s crucial also to update associated comments.

High-Level vs. Low-Level Comments

While discussing comments, it’s essential to distinguish between high-level and low-level comments. High-level comments provide an overview, offering a macro perspective. They’re typically found at the beginning of modules or functions and describe purpose, interactions, and overall behavior. On the other hand, low-level comments focus on specific lines or blocks of code, detailing intricate logic or highlighting potential pitfalls.

Conclusion

Comments are more than just annotations in your codebase. They’re a form of art that, when crafted meticulously, can guide, enlighten, and save time for any developer venturing through the code. However, they should never become a crutch for unclear code. The golden rule remains: Design software that’s easy to understand, and then use comments to enhance, not replace, clarity. As both Ousterhout and Uncle Bob assert, our primary aim should be clean, self-explanatory code, with comments playing a supporting role.