Chapter 15: Write The Comments First (Use Comments As Part Of The Design Process)

Core Idea

Write comments at the start, as part of design, not at the end. Comments written first are better, they improve the design because a hard-to-write comment reveals a bad abstraction, and they make documentation enjoyable. They cost little.

Frameworks Introduced

• The comments-first process (the author’s own sequence for a new class):
  1. Write the class interface comment.
  2. Write interface comments and signatures for the most important public methods, leaving the bodies empty.
  3. Iterate on these comments until the basic structure feels about right.
  4. Write declarations and comments for the most important instance variables.
  5. Fill in the method bodies, adding implementation comments as needed.
  6. When you discover a new method, write its interface comment before its body. Write each new instance variable’s comment together with its declaration.
  • Result: “When the code is done, the comments are also done.” There is never a backlog.
• Comments as a design tool (“a canary in the coal mine of complexity”):
  • A method or variable that needs a long comment is a red flag for a poor abstraction.
  • Judge interface complexity by its comment: short, simple, and complete means a simple interface.
  • Compare the interface comment with the implementation. If the comment must describe all the major features of the implementation, the method is shallow.
  • If a variable needs a long comment, you may have chosen the wrong variable decomposition.
  • Caveat: this works only if the comment is complete and clear. A cryptic or incomplete comment is not a measure of depth.
• The cost estimate: typing code and comments, including revisions, is unlikely to exceed about 10% of development time. Even if half of all lines are comments, comments are about 5% of development time, and delaying them saves only part of that. Stable abstractions from writing comments first probably save coding time, so comments first may even be faster overall.

Key Concepts

• Red Flag: Hard to Describe: the comment for a method or variable should be simple and complete. If that is hard to write, the design may be wrong.
• Delayed comments: written after the code, when the designer has “checked out mentally” and remembers the design poorly. They tend to repeat the code and miss the important things.
• “Otherwise you are just hacking code”: you must identify the essence of a variable or piece of code early in design.

Mental Models

• Look for “the design that can be expressed completely and clearly in the fewest words.” The simpler the comments, the better the design.
• Write a method’s interface comment before its body, so you focus on the abstraction without being distracted by the implementation.
• If you program strategically, writing comments should be fun, because comments are how you find the best design.

Anti-patterns

• Waiting until the code stabilizes: delay grows, the backlog becomes huge, and the documentation is never written. “don’t fool yourself: you probably don’t” have the discipline to go back.
• Treating documentation as drudge work: the author suspects this is the real reason most developers delay.
• A quick pass at the end to look respectable: comments that repeat the code and omit the design ideas.

Worked Example

Designing a class comments-first (an illustration of the author’s process, using the book’s IndexLookup case from ch13).

1. Write the class comment first: “This class is used by client applications to make range queries using indexes. Each instance represents a single range query.” If you find yourself writing about RPC names and private configuration constants, that is the canary: implementation is leaking into the interface.
2. Write the signature and comment for the main method, getNext, before writing any body: it returns the next object in the range, and NULL when there are none left.
3. Try to write the comment for isReady. If the only accurate description talks about internal rules and modules, the method’s abstraction is weak. A good comment says what “ready” means for the caller (the next getNext won’t block) and that calling it drives the lookup forward.
4. Iterate on these comments until each is short and complete. Then write comments for the key instance variables, then the bodies.
5. As you write bodies and discover helper methods, write each helper’s interface comment first. At the end, no documentation is left to write.

Key Takeaways

1. Start each class with its interface comment, then the comments for its key methods.
2. Write the interface comment before the method body, always.
3. Treat any long or hard-to-write comment as a design problem to fix now.
4. Don’t delay documentation to save rework; the saving is a few percent at most.
5. Try the approach long enough to get used to it, then judge it on comment quality, design quality, and enjoyment, as the author invites.

Connects To

• Ch 3: comments first is part of strategic programming.
• Ch 4: depth is visible in the length of interface comments.
• Ch 11: comments make it cheap to sketch and compare alternative designs.
• Ch 12: the “I don’t have time to write comments” excuse.
• Ch 13: what good interface comments contain; the IndexLookup example.
• Ch 19: test-driven development focuses on getting features working rather than on design.