Key takeaway: Code states what happens. Comments should state what code cannot express — intent, constraint, rejected alternatives and non-obvious cause.
The Comment That Costs More Than It Gives
A comment reading “increment the counter by one” above a line that increments a counter adds nothing the line did not already say. Worse, it now needs updating whenever that line changes. It will not be updated, so it will eventually be wrong, and a wrong comment is more harmful than no comment because readers extend trust to it.
Comments drift silently and nothing verifies them. A test fails when code and behaviour disagree. Nothing at all fails when code and comment disagree, which means the error persists indefinitely and misleads every subsequent reader.
What Code Genuinely Cannot Say
Four categories of information have no expression in code itself, and these are where comments earn their maintenance cost.
Why this approach and not the obvious alternative. A loop that pushes records sequentially looks like an obvious candidate for parallelisation. A comment recording that the vendor API returns 429 above two requests per second, that their support confirmed no batch endpoint exists, and the ticket number where this was established, prevents the next reader from making an improvement that reintroduces a resolved incident.
External constraints invisible from the local code. A field length limit of 32 characters looks arbitrary until a comment explains that a downstream mainframe truncates silently rather than erroring, producing corrupt records with no signal. That constraint lives in another system and cannot be inferred here.
Non-obvious correctness reasoning. A map accessed without a lock looks like a bug. A comment stating that it is populated during initialisation and only ever read afterwards, and that adding any writer requires adding a mutex, documents an invariant. Someone who adds a write without reading it introduces a data race that surfaces once a month under load.
Deliberate deviations from the standard approach. Choosing a manual clone over a built-in function looks like ignorance unless a comment records that the built-in drops the prototype chain and callers rely on instance checks downstream.
Where Comments Pay Continuously
Public API documentation differs from inline commentary and returns value on every use. A caller should not need to read your implementation to learn whether a method throws, mutates its argument, or requires a particular call order. That information belongs in the signature’s documentation, not in the reader’s memory.
Regular expressions deserve an example alongside them. A pattern matching email addresses is faster to verify against a sample string than to parse mentally, and the example doubles as documentation of intent.
Non-obvious constants need provenance. A retry limit of three is meaningless as a bare number. The same constant with a note that beyond three attempts the 99th percentile exceeds the gateway timeout is a decision with reasoning attached, and it tells the next person what to reconsider if the timeout changes.
The Refactoring Test
Before writing any comment, ask whether a better name removes the need for it. A comment explaining what a function does usually indicates the function needs a clearer name or should be decomposed.
A condition combining several cryptic single-letter fields needs a comment. The same logic extracted into a well-named predicate method needs none — the explanation moved into the code, where it cannot drift out of sync with behaviour. That is strictly the better outcome, and it should be the first thing attempted.
The Bottom Line
Delete comments that restate code. Write comments that capture why a choice was made, what external constraint applies, and which alternative was rejected and for what reason. When the urge arises to explain what code does, try renaming it first — a comment that becomes unnecessary is better than one that becomes stale.
