comments-docs

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

Useful comments say things the code does not. If another developer could write the same comment just by reading the surrounding code, it doesn't need to exist and should be deleted.

Rephrasing an entity name doesn't cut it. A comment about fetchUserProfile that says "Fetches the user profile" is still noise.

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.

Comment	Implementation	Signal
Short, simple	Substantial	Deep — hides complexity well
Long, complicated	Short	Shallow — description nearly as complex as code
Must describe internals	Any	Leaky abstraction

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: design intent has scrolled out of the context window, and a finished implementation contaminates your perspective, so you end up restating the code 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 are a small fraction of total output — well under 10% of the tokens spent on a task. 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 is a default bias, not a hard rule: treating comments as "junk" causes them to be skipped, and useful design context goes unrecorded for every collaborator — human or agent — who reads the code later. 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. Check for comment rot: Does each comment's claims still match the code and behavior it describes? Flag mismatches.
7. 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).

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.