Comments that carry information the code cannot

Goal

Comments that a maintainer is glad to find: the reason for a surprising decision, the external constraint that forced it, and the trap they are about to walk into.

Prerequisites

Code whose structure and names already say what it does; comments are not a substitute for that.

Steps

1. Before writing a comment, ask whether a better name, a smaller function or an assertion would make it unnecessary.
2. Write the why: the business rule, the bug that this guards against (with a ticket or commit reference), the specification section that requires the odd behaviour.
3. Write constraints and consequences: "must run before X because…", "this value is persisted, changing it needs a migration".
4. Mark temporary measures with the condition for removal, not just TODO: "remove once all clients send version ≥ 3 (see metrics dashboard)".
5. Keep the comment adjacent to the code it describes; a comment at the top of a file about a line in the middle rots.
6. In review, treat a comment that restates the code, or contradicts it, as a defect.

Expected result

Comment density falls while their information content rises; readers stop skipping them.

Limits and test basis

Public API docstrings follow their own rules (they describe contracts). Generated code and configuration may need more explanation than hand-written code. No measurement is claimed.