The load-bearing comment

The advice that comments should explain why rather than what is correct and too abstract to act on. Here is the concrete version: a comment earns its place when it records information that could not have been derived from reading the code, and that someone would otherwise have to rediscover.

Everything else is decoration that will drift out of sync.

the four that earn their place#

The constraint that came from outside.

# The vendor's API rejects batches over 500 even though their docs say 1000.
# Confirmed with their support, ticket #48812, March 2026.
BATCH_SIZE = 500

Nothing in the code can tell you this. Without it, someone raises the number back to 1000 in eighteen months, ships it, and spends a day debugging.

The alternative that was tried and failed.

// Tried sync.Map here first. It was slower for this access pattern — writes
// dominate and the keys are hot, which is the case sync.Map is worst at.
// Benchmark: bench/cache_test.go, BenchmarkHotKeys.

This is the highest-value comment there is, because it stops the next person repeating your experiment. It converts a day of their work into a paragraph.

The non-obvious ordering.

// Must run before initAuth(): the session store reads the feature flag cache,
// which is populated here. Reversing these fails silently — the user gets the
// default flag set rather than an error.

"Fails silently" is the part that matters. A comment marking a trap is worth more than one marking a happy path.

The deliberate weirdness.

// Deliberately not using the iterator: this is on the hot path and the
// bounds checks cost ~8% on the profile. See PERF-221.

Without this, a well-meaning reviewer "cleans it up" and quietly regresses performance. Deliberate ugliness that isn't labelled reads as accidental ugliness, and accidental ugliness gets fixed.

the ones that do not#

Restating the line. // increment counter above counter += 1. This is the canonical example and it is still everywhere.

Section headers in a long function. // ---- validation ---- is a request for an extract function refactor wearing a disguise.

Commented-out code. Delete it. Git has it. A block of dead code with no note is a question nobody can answer: is this a work in progress, a rollback, or something someone forgot?

Changelogs in the file header. // 2019-03-04 JS: added retry logic. That is what the commit log is for, and it is accurate there.

Comments that duplicate the type. // returns a list of user IDs above fn user_ids() -> Vec<UserId>. The signature already said it, and the signature cannot go stale.

the decay problem#

Every comment is a claim that is not checked by anything. The code changes; the comment does not; now it is actively misleading, and a misleading comment is worse than no comment because it is trusted.

Three things reduce the decay:

Put it as close to the fact as possible. A comment above the line it describes survives longer than one at the top of the file describing behaviour forty lines down.

Prefer things that are checked. A well-named function, a type, a test with a descriptive name, an assertion — all of these carry the same information and break when they become false. Reach for those first; comment only what none of them can express.

Reference something durable. A ticket, a benchmark file, a commit hash, a support ticket number, a link to the vendor's documentation. Then a reader who doubts the comment can check it rather than guess.

the test#

Before writing a comment, ask: could I encode this in a name, a type, or a test instead?

If yes, do that — it will be checked, and the comment will not.

If no — if the information genuinely lives outside the code, in a vendor's behaviour or a decision someone made or an experiment that failed — write it down. That is exactly the case comments exist for, and those comments will still be earning their keep in a decade.