When comments lie

A redundant comment restates the code and adds a second thing to keep in sync. If the comment says exactly what the next line says, it carries no information — it just doubles the surface that can drift.

// increment i by one
i = i + 1;

// set the user's name to the given name
user.name = name;

// loop over all the items
for (const item of items) { /* ... */ }

None of these tell a reader anything the code doesn’t already shout. Worse: when i = i + 1 later becomes i += 2, the comment is now wrong, and you’ve manufactured a lie out of something that was merely useless. The fix is not to write a better restatement — it’s to delete the comment and, if the line was unclear, make the code clearer (a better name, a smaller function). The code is the source of truth; don’t paraphrase it.

An outdated comment is a bug with no test to catch it. This is the dangerous family, because it doesn’t just waste a glance — it sends you down the wrong path with full confidence.

// timeout is 30 seconds
const TIMEOUT_MS = 10_000;

// NOTE: assumes the list is already sorted
function median(xs: number[]): number {
  return xs[Math.floor(xs.length / 2)]; // returns the wrong element if xs is NOT sorted
}

The first comment contradicts the literal beside it; a reader who trusts the prose computes with the wrong number. The second is worse — it documents a precondition (already sorted) that nothing enforces, so the function silently returns garbage the day a caller forgets. Comments like these decay precisely because they sit next to code that changes without them. Every comment you keep is a maintenance liability you have signed up to update by hand, forever, with no compiler reminding you.

Commented-out code is dead weight — delete it; version control remembers. A block of code “kept just in case”, wrapped in // or /* */, is one of the most common and least defensible comments.

function price(order: Order): number {
  // const tax = subtotal * 0.2;          // old flat rate
  // return subtotal + tax;
  // return subtotal + applyOldDiscount(subtotal);
  return subtotal + taxFor(subtotal, order.region);
}

It answers no question the reader has. Is it the next thing to ship? A fallback? An abandoned experiment? Nobody knows, so everybody leaves it — and it accumulates, rotting alongside the live code, confusing every future search and review. The original is not lost: git log -p and git blame hold every line you ever deleted, with the commit that explains why. Deleting commented-out code loses nothing and removes noise. Keeping it preserves nothing and adds doubt.

A good comment explains WHY, not WHAT — the one thing code genuinely can’t say. Code is excellent at expressing what it does and how. What it cannot express is the reasoning that isn’t in the syntax: the constraint you’re working around, the consequence of a “harmless”-looking change, the non-obvious choice you made on purpose.

// Stripe rounds half-up; we must match their cents exactly or the
// reconciliation job flags a 1-cent mismatch and pages on-call.
const cents = Math.round(amount * 100);

// DO NOT parallelise: the upstream API rejects concurrent writes
// to the same account with a 409 we can't retry cleanly.
for (const tx of txs) await post(tx);

// Binary search instead of indexOf: this runs per keystroke on a
// 50k-row list; linear scan dropped input latency below 60fps.
const i = lowerBound(rows, query);

Each of these earns its place. None restates the code; each captures rationale a future maintainer would otherwise have to rediscover by breaking something. The litmus test: if you deleted the comment, could a competent reader recover the information from the code alone? For what/how, yes — so the comment is noise. For why (the 409, the reconciliation, the 60fps budget), no — so the comment is doing real work. Warnings of consequence, encoded intent the type system can’t capture, and // TODO(JIRA-1234): … markers tied to a ticket are all variants of the same legitimate job: recording what the code can’t.