Skip to content
← All articles

Stop Writing Comments That Restate the Code

1 min read
code-qualitycraft

// increment the counter above counter++ earns nothing. The code already said that, and said it more precisely.

The comment that pays for itself

// Firestore hands back Timestamp objects, which Next cannot serialize across
// the server/client component boundary. Normalize everything date-ish to ISO.
function toIso(value) { /* ... */ }

Nobody reading toIso could have derived that. It records a constraint discovered the hard way — probably through a confusing build error — and it stops the next person from "simplifying" the function back into a bug.

What deserves a comment

  • Constraints from outside the file. Platform limits, API quirks, a spec requirement.
  • Rejected alternatives. "Tried X, it breaks under Y" saves someone a day.
  • Non-obvious ordering. Why this call must happen before that one.
  • Deliberate weirdness. Code that looks wrong but is not.

What does not

Anything a careful reader gets from the code in five seconds. If the code is unclear, fix the code — a comment is a worse fix than a better name.

The test

Delete the comment. If nothing is lost, it should not have been there.