code-commentslisted

# Code comments The default number of comments is zero. A comment is a liability: it isn't type-checked, isn't tested, and rots the moment the code beside it changes. Earn each one. Let the code and the tests speak. A well-named function, a clear test name, and a small function body explain *what* far better than prose ever will. If you reach for a comment to explain what code does, fix the code instead - rename the variable, extract the function, split the branch. ## The only good reason to comment: non-obvious WHY Write a comment when a reader who understands the language and the codebase would still be surprised - and the surprise lives outside the code itself: - A **hidden constraint**: "the upstream API caps page size at 100, larger values 400." - A **subtle invariant**: "callers must hold the lock; we mutate shared state here." - A **workaround** for a specific, named bug: "round-trip through string - `structuredClone` drops Dates in node <20." - **Surprising behavior** that looks like a mistake but isn't: "yes, `<=` - the boundary row is inclusive per the spec." The test: if removing the comment would let a competent reader introduce a bug, keep it. Otherwise delete it. ## Never write these - **Restatement of the code.** `// increment i` over `i++`. `// loop over users` over `for (const u of users)`. The code already says this. - **Task / ticket / PR references.** No `// JIRA-1234`, `// added for the onboarding flow`, `// see PR #87`, `// fix from issue 42`. Th