From 0158e1d0fff921b9d51b776bfa20080622d92eaf Mon Sep 17 00:00:00 2001 From: fkwp Date: Wed, 23 Sep 2026 21:01:36 +0200 Subject: [PATCH] Say what earns a comment its place - Add a comments section to the code style: no comment by default, the reason only, and the kinds that go stale. - Point to it from the PR checklist in AGENTS.md. - Drop the one-clause rule it replaces. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 2 ++ docs/agents/code-style.md | 26 +++++++++++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f0a94112c..a47c41630 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,6 +48,8 @@ pnpm i18n:check - View model + marble tests, thin view, a story per state, an e2e spec. - Any new shared component called out explicitly, with why nothing existing fit. - Template filled for real: what, why, before/after screenshots, repro steps. +- Comments only where the code can't give the reason — see + [code-style.md](docs/agents/code-style.md#comments). - Anything that redraws continuously — an animation frame, a stream — says what it costs, or better, counts the redraws in a test. - Branch `/`. Plain imperative commit subjects, no prefixes. diff --git a/docs/agents/code-style.md b/docs/agents/code-style.md index 1907aaf82..81bfda050 100644 --- a/docs/agents/code-style.md +++ b/docs/agents/code-style.md @@ -31,7 +31,31 @@ copy, the PR says so. - **Suites.** Test cases first, helpers below. Older suites invert this; follow the rule in new ones, don't reorder old ones. - **Names.** What a thing means, not what it is made of: `naturalLayout$`, not - `computedLayout$`. Comments explain why, never what. + `computedLayout$`. + +## Comments + +No comment is the default. One earns its place by giving a reason the code +cannot: a platform quirk, an outside constraint, a trap that looks like a +simplification. + +- Say the reason, then stop. Test each sentence: does the reason still stand + without it? If so, cut it. Most reasons fit on a line, so a long comment is + worth a second look — it is usually carrying something that isn't one. +- Never describe: + - layout or placement — the stylesheet says it, and changes without the + comment; + - the context around the code — it moves without touching the line; + - design measurements — the design is the source; + - how a decision was reached, or what was rejected — that goes in the PR body + or the feature spec; + - what the next line does, or what an assertion checks. +- No spec ids (D11, AC23) and no browser lists — both go stale silently. +- In tests, comment only structure that looks wrong but isn't: batching, timers, + why this scroll position. + +Before keeping one: would it still be true after a CSS change or a refactor of +its caller? If not, cut it. ## TypeScript, React and RxJS idiom win on a clash