Minimal Comments

Most code needs no comment. Names, types and structure carry the meaning; a comment is the fallback for the rare line that cannot be made clear on its own.

Why: A comment is a second copy of an intent the code already states, and copies drift. Every comment spent on the obvious taxes the one that matters.

The rule

• Inline code has no comments by default: not the step a line takes, the branch a condition guards, the phase a block belongs to.
• Before commenting an unclear line, make it clear: rename, extract, shrink. Comment only what survives that, and say why, not what.
• What earns one: a reason the code cannot show, a workaround for something external, code that does the opposite of what it appears to do, an invariant a caller must keep.
• At most one doc comment per function, type or module, at its head, and only when the name and signature leave a question. Behaviour spanning units lives in the document read before the code, never repeated in it.

Write for a reader who never saw the alternative

The comment describes the code as it stands, not the path that produced it. This is where a long session leaks: having just weighed two designs, it explains the one it rejected, or cites a constraint that only ever bound the abandoned path. The reader arrives cold, sees a claim nothing in the file supports, and cannot tell whether it is load-bearing.