commentslisted

# Code comment guidelines **Default: write no comments.** A comment must justify its existence; the absence of a comment is the right answer almost always. ## When a comment IS warranted Only when the **WHY** is non-obvious and a future reader would otherwise be confused or break the code: - A hidden constraint (e.g. "API requires this header lowercased — server rejects mixed case"). - A subtle invariant (e.g. "must run before X is mounted, otherwise the event listener attaches to the wrong target"). - A workaround for a specific bug or spec quirk (e.g. "Safari 17 fires `focus` twice — debounce"). - Behavior that would surprise a competent reader of this code. Keep it to **one line** wherever possible. Two lines max. Never a paragraph, never a multi-line block, never a docstring with sections. ## When a comment is NOT warranted (delete or skip) - Restating WHAT the code does ("// increment counter", "// loop through users") — well-named identifiers already do that. - Narrating the change or its origin ("// added to fix bug #123", "// used by the X flow", "// previously called Y"). That belongs in the PR description and rots as the codebase evolves. - Section headers ("// === Helpers ===", "// --- Validation ---") inside a normal function body. - Restating type annotations or signatures. - TODO/FIXME without a tracked issue or owner — either fix it now or file it; don't leave drift markers. - Commented-out code. Delete it; git remembers. ## How to apply 1. Before writ