Chapter 12: Why Write Comments? The Four Excuses

Core Idea

Comments capture information that was in the designer’s mind but can’t be represented in code. Without them you can’t build abstractions, because the only abstraction left is a declaration. The four usual excuses for not commenting don’t hold up.

Frameworks Introduced

• The four excuses, and the answers:
  1. “Good code is self-documenting.” A “delicious myth, like a rumor that ice cream is good for your health.” Good names reduce the need for comments, but code can’t express the informal interface (what a method does, what its result means), the rationale for decisions, or when it makes sense to call a method. Expecting readers to read implementations pushes you to write many short, shallow methods, and readers still have to read the nested ones.
  2. “I don’t have time to write comments.” If documentation can be deprioritized, it never gets written, because there is always something more urgent. Typing code is probably no more than 10% of development time; even if typing comments takes as long, comments add about 10% at most. Interface comments written during design (ch15) pay back immediately.
  3. “Comments get out of date and become misleading.” Large documentation changes follow only large code changes, which take longer anyway. Avoid duplication, keep comments near the code (ch16), and use code reviews to catch stale comments.
  4. “The comments I have seen are all worthless; why bother?” This excuse has the most merit. Most existing comments are so-so, but writing good ones is not hard once you know how (ch13).
• Comments are fundamental to abstraction: “If users must read the code of a method in order to use it, then there is no abstraction.” A declaration alone lacks essential information. With start and end arguments to a substring method, you can’t tell whether the character at end is included or what happens if start > end.

Key Concepts

• What comments capture: everything from low-level details (a hardware quirk behind tricky code) to high-level concepts (a class’s rationale).
• Human language in comments: less precise than code but more expressive, which allows simple, intuitive descriptions.
• Comments and the symptoms of complexity: documentation reduces cognitive load (it tells you what you need and lets you ignore the rest) and reduces unknown unknowns (it makes clear which code and information matter). It doesn’t address change amplification.
• Comments and the causes of complexity: documentation clarifies dependencies and fills gaps that cause obscurity.

Mental Models

• Think of comments as part of the design, not as drudge work. “without comments, you can’t hide complexity,” and “a good software design loses much of its value if it is poorly documented.”
• Write for your future self too. After a few weeks away from code, you will have forgotten many details of its design.
• The author hopes to convince readers of three things: good comments make a big difference, they aren’t hard to write, and writing them “can actually be fun.”

Anti-patterns

• Treating “read the code” as documentation: slow for readers, impractical in large systems, and it pushes code toward shallow methods.
• Letting documentation be optional under time pressure: you end up with none.
• Judging all comments by bad ones: the fix is better comments, not no comments.

Worked Example

The substring declaration. A method that extracts a substring takes two arguments, start and end. From the declaration alone, a caller can’t tell:

• whether the extracted substring includes the character at end;
• what happens if start > end.

Without a comment, the only way to answer is to read the implementation, and then the method provides no abstraction. A short interface comment answers both questions and lets the caller ignore the implementation. Chapter 10 shows the further step of defining out-of-range cases so that no exception is needed.

The time budget. Suppose typing code is 10% of your development time and the rest is designing, compiling, and testing. Typing comments for as long as you type code (a safe upper bound) adds about 10% to development time, which good documentation recovers quickly.

Key Takeaways

1. Treat comments as the way to express the parts of an interface that code can’t.
2. Don’t skip comments for time; they cost at most about 10% and pay back quickly.
3. Keep comments current through placement near code, no duplication, and code review.
4. Learn to write good comments instead of dismissing all comments because many are bad.

Connects To

• Ch 2: the symptoms and causes of complexity that documentation addresses.
• Ch 3: the investment mindset answers the “I don’t have time to write comments” excuse.
• Ch 4: formal versus informal interfaces.
• Ch 13: how to write good comments.
• Ch 14: names reduce, but don’t remove, the need for comments.
• Ch 15: comments written first, as a design tool.
• Ch 16: keeping comments up to date.