Comments & Documentation Review Lens

When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.

Comments are not recording a design that already exists. They are the medium in which the design is discovered. Code captures mechanism. Comments capture meaning. Even a perfect programming language could not replace them. The information types are distinct.

When to Apply

• Reviewing code with comments (or conspicuously lacking them)
• When writing new interfaces and considering documentation strategy
• When comments feel useless or redundant
• When a module is hard to use despite having documentation

Core Principles

The Guiding Principle

“Comments should describe things that aren’t obvious from the code.” — John Ousterhout, A Philosophy of Software Design

“Obvious” is from the perspective of someone reading the code for the first time, not the author. If a reviewer says something isn’t obvious, it isn’t. Don’t argue, clarify.

Four Comment Types

1. Interface Comments

What and why for callers. Must be sufficient to use the interface without reading implementation. Operate at two levels: intuition (a sentence giving the mental model) and precision (argument/return docs more specific than the code). A comment that says “offset” does not specify inclusive vs exclusive.

2. Implementation Comments

What a block does (high-level) and why, not line-by-line how. For variable comments, think nouns, not verbs: describe what the variable represents, not how it’s manipulated.

3. Cross-Module Comments

Document dependencies spanning module boundaries. Place at a convergence point, or maintain a central designNotes file with labeled sections per topic and short pointer comments in the code (// See "Zombies" in designNotes). Neither approach is perfect. This is a genuinely unsolved problem.

4. Data Structure Member Comments

Each field should have a comment capturing what’s not obvious from the type or name: what it represents, units, valid ranges, boundary conditions (inclusive/exclusive), nullability, resource ownership (who frees/closes), invariants and relationships to other fields.

“Comment Repeats Code” Test

“Could someone who has never seen the code write the comment just by looking at the code next to the comment? If the answer is yes, then the comment doesn’t make the code any easier to understand.” — John Ousterhout, A Philosophy of Software Design

If yes, delete it. Use different words from those in the entity name. A comment for fetchUserProfile that says “Fetches the user profile” contributes nothing.

Hard-to-Describe Signal

When a comment must be long, qualified, or convoluted, that’s a design problem, not a writing problem. Simple descriptions come from well-designed abstractions.

Comments-First Workflow

Write interface comments before method bodies. If a comment is hard to write, the abstraction is wrong, and you find out before writing the implementation. Comments written after-the-fact produce worse results. Your memory of your intent has faded and you end up justifying the code you wrote instead of capturing why you wrote it.

1. Class interface comment: purpose and abstraction, before anything else
2. Public method comments + signatures: bodies empty. Iterate until structure feels right
3. Instance variable declarations + comments: once interface stabilized
4. Fill in method bodies: implementation comments as needed. Comments are already done

See the full workflow for the complexity canary tests and cost analysis.

The Four Excuses

• “Good code is self-documenting.” A signature gives you types and parameter names. It does not tell you when to call the method, what the return value means, or why the method exists. That information lives in comments. When readers must study an implementation to use it, a module offers no real abstraction.
• “I don’t have time.” Comments add at most 10% to typing time. Reframed: “I don’t have time to design.”
• “Comments get out of date.” Manageable with discipline at the point of change and code review.
• “All comments I’ve seen are worthless.” Solvable with technique, not intention.

Why “Comments Are Failures” Is Wrong

Robert Martin argues in Clean Code that comments are failures and signs that the code wasn’t expressive enough. His alternative is method extraction: replace a commented block with a well-named method.

Method names work for simple operations. extractSubstring is better than a comment above a five-line block. But names can hit a ceiling. A name can say what a method does but it won’t say why, describe the preconditions or explain non-obvious constraints. A name alone cannot carry that, but a comment can. Taken to the extreme, method extraction encourages splitting code into infinite small methods, which can increase complexity rather than reduce it.

The issue ends up being cultural. If a team thinks comments are “junk” or fail to be “real documentation”, then they avoid creating them and useful design context goes unrecorded. The best place for design context is right next to the code it describes, not in a separate document that the reader may never find or even know to look for.

Review Process

1. Classify existing comments: Interface, implementation, cross-module, or data structure member?
2. Check for repeats-code: Same words as the entity name?
3. Check for missing interface comments: All public interfaces documented? Both intuition and precision?
4. Evaluate hard-to-describe: Long or convoluted comments? Investigate the design.
5. Check cross-module docs: Dependencies documented? Canonical location?
6. Recommend: Delete noise, add missing interface comments, flag hard-to-describe as design problems

Red flag signals for comments are cataloged in red-flags (Comment Repeats Code, Implementation Documentation Contaminates Interface, Hard to Describe, Information Leakage).

References

For deeper coverage, load on demand:

• Comments-first workflow: Full 6-step process, complexity canary tests, cost analysis, and why after-the-fact comments are a red flag.