code-commentslisted

# Code Comments ## Principle A comment describes the code **as it reads right now**. The story of the change — why you picked this value, what it used to be, what incident caused it, what not to "clean up" — belongs in the commit message and PR, where `git blame`/`git log` surfaces it on demand, not in the file forever. **Default: no comment.** Good naming and types are the primary documentation. A comment that restates what a well-named component/prop/function already says is noise, not help — every future reader pays for it. ## Where the "why" goes | Fact | Put it in | |---|---| | Why you chose this approach/value | Commit message | | What it used to be / migrated from | Commit message | | Incident/ticket backstory | Commit message (ref the ticket) | | "Don't change this" | Commit message — `git blame` is the guard | | What the code does | Naming, not a comment | | A genuine external gotcha | One terse comment (see below) | ## When a comment earns its place Only when a reader of the **current** code would be misled without it, and the fact doesn't change if the code around it is renamed/refactored: - An external constraint invisible in the code: a browser quirk, an API that silently caps results, a CSS property needed to defeat a specific Safari bug. - A non-obvious ordering/timing requirement (e.g. why a `useEffect` must run before another, a race the code works around). - A unit or format a name can't carry (`delayMs`, not `# milliseconds`). One line. If rena