Writing Comments

Write every comment for exactly one reader: a competent developer seeing this file for the first time, with no access to the pull request, the conversation that produced the code, other files, or the author's head. These rules are distilled from the best-commented codebases in the wild — Go's standard library, SQLite (whose source is ~35% comments explaining intent), Redis, Rust's std — which independently converge on the same conventions.

The stranger test (master rule). Cover the function body. Hand the comment plus the signature to someone who has never seen this repository. They must be able to say what the thing does, and every noun in the comment must resolve to a parameter, a named identifier in the signature, or a term the comment itself defines. A noun that needs the PR, the chat, or another file to decode fails the test.

1. Start with the name. The first sentence names the thing and states what it does, in a complete present-tense sentence. Booleans use Go's fixed verb: reports whether.

   // BAD:  True when the caller asked to resume.          (who is "the caller"?)
   // GOOD: canRetry reports whether job's retry budget allows another attempt.
   

   Functions: third-person verb — returns, parses, creates ("Marshal returns the JSON encoding of v"). Types: a noun phrase ("A fixed-size ring buffer of recent log lines."). A comment forced to begin with the identifier cannot have a mystery subject.

2. Nouns come from the signature. Refer to parameters and fields by their names — requested, account.freezeReason — never by role-words invented for the comment ("the caller", "the guard", "the retry path"). If the comment needs a concept the code doesn't name, that's a naming gap: name it in code first. Resolution is not comprehension: pointing a noun at an existing identifier passes only if that identifier would itself survive the naming skill's stranger check — resolving "the override" to resolveBillingFreezeOverride merely relocates the mystery when nothing anywhere says what is overridden. When the honest fix is a rename that ripples through call sites, report the naming gap as a finding with its blast radius instead of silently settling for prose; the churn budget is the human's call.