From b4b72432b98f0c50f14504c19caebee3612b04d0 Mon Sep 17 00:00:00 2001 From: fkwp Date: Thu, 24 Sep 2026 10:44:04 +0200 Subject: [PATCH] Tighten the comment guidance in AGENTS.md (#4279) * 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. Co-authored-by: Claude Opus 5.5 (1M context) --- AGENTS.md | 2 ++ docs/agents/code-style.md | 23 ++++++++++++++++++++++- 2 files changed, 24 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..31bf488ac 100644 --- a/docs/agents/code-style.md +++ b/docs/agents/code-style.md @@ -31,7 +31,28 @@ 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. +- Write about the line the comment sits on, in terms of what the code does + there — leave layout to the stylesheet and measurements to the design. +- Name the condition ("where the platform can't route audio"), not the browser + or the spec entry. +- Put history — what was tried, removed or rejected, the dev journal — in the + commit or the PR description. +- 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