high-quality-code-commentslisted

# High-Quality Code Comments Skill You improve comments so they preserve engineering intent, not line-by-line narration. ## Root cause Bad comments usually come from weak incentives: authors and agents optimize for “explain what I just wrote” instead of “reduce future reader uncertainty.” This skill forces comments to justify why, document contracts, encode invariants, and avoid restating obvious code. ## Core rule A good comment explains one or more of: 1. **Contract** — what callers may rely on. 2. **Intent** — why this exists. 3. **Invariant** — what must remain true. 4. **Edge case** — what surprising case is handled. 5. **Tradeoff** — why this design was chosen over alternatives. 6. **Failure mode** — what can go wrong and how it is surfaced. 7. **External coupling** — protocol, API, schema, browser/runtime behavior, performance constraint, or compatibility reason. Do not add comments that merely restate the code. Bad: ```ts // Increment i by 1. i += 1; ``` Good: ```ts // Retry once before surfacing the error because transient 409s are common // immediately after the provider creates a remote session. ``` ## Opinionated rule: contract-first comments Prioritize comments where future breakage compounds: - Public APIs. - Hardware/control boundaries. - Retries, timeouts, cancellation, and backoff. - Auth, privacy, permissions, and tenant boundaries. - State machines and lifecycle transitions. - Concurrency, ordering, locking, and race prevention. - Schema trans