Comments hold what was in the designer's head but can't live in code. Without an interface comment there is no abstraction: callers have to read the body.
Mode A — new code (comments first)
- Class or module interface comment: what abstraction it provides, what one instance represents, and its limits.
- Signatures plus interface comments for the main public methods. Leave the bodies empty.
- Iterate on those comments until they are short and complete. If a comment can't be both, the design is wrong. Fix the design, not the prose.
- Comment the key fields, then write the bodies. Every new method gets its comment before its body.
Mode B — audit existing code
Check in this order:
- Interface comment gives the caller-visible behavior, each argument and return value (precisely), side effects, errors, and preconditions. A caller should never need to read the body.
- No implementation in the interface comment. Internals belong inside the body.
- Doesn't repeat code. Test: could someone write this comment from the adjacent line alone? Use different words from the name.
- Precision for fields and parameters: units, inclusive or exclusive bounds, what null means, who frees or closes it, invariants. Describe what it is (nouns), not how code toggles it.
- Implementation comments explain what a block does and why, not how. Put one before each major phase or complex loop.
- Cross-module rules go in one place that people will find: the enum everyone edits, or a
designNotessection referenced with// See "X" in designNotes. - Code, not commit log. If a future reader needs the "why", put it in the code.
- Maintenance. Keep each comment next to the code it describes, document each fact once, and check the diff for stale comments before committing.
Names
- Create an image. Seen alone, does the name let the reader guess what it is? Aim for 1–3 words.
- Precise over generic. Prefer
numActiveIndexletstocount,cursorVisibletoblinkStatus. Booleans are predicates. - Consistent. One name per concept and one concept per name. If two kinds of the same thing exist, distinguish them (
fileBlockvsdiskBlock), ideally with distinct types. - Name length grows with the distance between declaration and use.
iis fine in a 3-line loop. - Hard to pick a name means the thing probably has no clean definition. Split it.
Output
In Mode A, the skeleton: comments and signatures, no bodies. In Mode B, path:line — problem → rewritten comment or name, plus a list of any design smells the comments exposed.