code-comments

A comment is for the next person reading the code, years from now, with no knowledge of the feature, ticket, or conversation that produced it. It earns its place by answering one of two questions:

1. What does this do? — the behavioral contract: inputs, outputs, failure modes, decision rules.
2. What must stay true? — a constraint or invariant the code itself cannot express, stated so a future "simplification" doesn't break it.

Everything else — why the feature exists, what it replaced, what trade-off was weighed, why the change is safe — belongs in the plan doc, PR description, or commit message, not in source.

Banned patterns

Justification / cost-benefit narrative. The comment defends a decision instead of describing behavior.

// BAD: New values of identity fields pass through without an LLM call —
// translating a `model_uid` would corrupt data, which is worse than the
// bill this feature saves.

// GOOD: 'identity' — every value of the field is byte-identical to its
// translation; 'translated' — at least one value differs. Determines
// whether an unmatched value may pass through untranslated.

Implementation history. "Before this change…", "previously this retranslated the whole blob…", "this used to be…". The reader has git.

Reviewer-directed commentary. "This is safe because…", "note that we correctly…", "this should always succeed". If it states no behavior or constraint, delete it; if a failure genuinely can't happen, the code should not handle it.

Narrating the next line. // loop over the chunks above a loop over the chunks.

Feature tours. Module headers that explain the product problem the module solves. Describe what the module's functions do; one or two sentences.

What deserves a comment

A constraint the code cannot show. The strongest kind of comment — it prevents a correct-looking edit that breaks a non-local assumption:

// GOOD: Non-ASCII must fail this test: CJK prose contains no spaces, so a
// whitespace check alone cannot exclude it.
const IDENTIFIER_SHAPED = /^[A-Za-z0-9_\-./+:@]*$/;

A behavioral contract on an exported function. Docblock stating what it returns for which inputs, including the failure/null cases. Present tense, declarative, no "we".

A guard against wrong unification or wrong simplification. When a future reader will be tempted to merge two similar-looking things or delete a "redundant" branch, state the behavioral difference or the invariant — one sentence, as fact, not story:

// GOOD: Unlike nestedExpressionFields.ts (which skips non-literal values
// inside a field whitelist), leaf collection here is all-or-nothing: any
// non-literal node disqualifies the entire chunk.

Style

• Match the density and idiom of the surrounding file; don't out-comment it.
• Docblocks (/** … */) on exported functions and types; // for local facts.
• Present tense, third person: "Returns null unless…", not "we return" or "this will return".
• If a comment needs a paragraph of justification to make sense, the justification goes in the PR description and the comment shrinks to the invariant.

Review test

Before keeping a comment, ask: if the feature discussion had never happened, would this sentence still be true and useful? Comments that only make sense as part of the implementation conversation ("this fixes the $70 re-billing", "worse than the bill this saves") fail the test.