From d0798436567a40815de0bdc43dc55f25dee9d1fe Mon Sep 17 00:00:00 2001 From: fkwp Date: Thu, 24 Sep 2026 10:29:45 +0200 Subject: [PATCH] Say what a comment should do rather than what it shouldn't - Turn the list of things never to describe into positive bullets. - Fold in history of what was removed, and the dev journal, as belonging in the commit or PR description. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/agents/code-style.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/agents/code-style.md b/docs/agents/code-style.md index 81bfda050..31bf488ac 100644 --- a/docs/agents/code-style.md +++ b/docs/agents/code-style.md @@ -42,15 +42,12 @@ 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. +- 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.