comment-auditlisted

# Comments The default is no comment. The code says what it does; a comment is for what the code cannot say. Every rule below is that one rule applied twice: once when deciding whether to write a line, once when deciding whether to keep it. ## Never write Five reasons a comment fails, and a report names the one it fell under. **It duplicates the code.** - **The obvious**: Anything recoverable by reading the line. `// set the title`, `// loop over items`, `// return the result`, `// YYYY-MM-DD` above a `.slice(0, 10)`. When the comment exists because the name is bad, the fix is the rename, so flag it rather than deleting the only explanation. - **What the types already say**: `@param userId The user id`. Document what the type cannot: units, ownership, what `null` means, the format of a string. **It belongs somewhere else.** - **History**: "was sized for English", "had drifted", "used to be a utility", and diff narration like "new", "updated", "moved from utils". How the code got here is the commit message's job. The exception is a fact that stops the obvious wrong edit, and it survives only in present tense. "The columns are `rated_at` and `message_agent`, not the `timestamp`/`agent` they look like" earns its line; "#217 renamed these" does not say the same thing to someone who was not there. - **Design rationale at length**: A paragraph arguing for a decision belongs in the PR description or a design doc. The sentence naming the constraint can stay. - **Attribution**: