Matrix/element-call-Github
1
0
Fork 0
mirror of https://github.com/vector-im/element-call.git synced 2026-09-25 22:35:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tighten the comment guidance in AGENTS.md (#4279)

Browse Source 
* 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) <noreply@anthropic.com>
This commit is contained in:
fkwp
2026-09-24 08:44:04 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent ac1f5e2c8c
commit b4b72432b9
2 changed files with 24 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2
View File
@@ -48,6 +48,8 @@ pnpm i18n:check
- View model + marble tests, thin view, a story per state, an e2e spec. - 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. - Any new shared component called out explicitly, with why nothing existing fit.
- Template filled for real: what, why, before/after screenshots, repro steps. - 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 - Anything that redraws continuously — an animation frame, a stream — says what it
costs, or better, counts the redraws in a test. costs, or better, counts the redraws in a test.
- Branch `<handle>/<topic>`. Plain imperative commit subjects, no prefixes. - Branch `<handle>/<topic>`. Plain imperative commit subjects, no prefixes.
docs/agents/code-style.md
+22 -1
View File
@@ -31,7 +31,28 @@ copy, the PR says so.
- **Suites.** Test cases first, helpers below. Older suites invert this; follow the - **Suites.** Test cases first, helpers below. Older suites invert this; follow the
rule in new ones, don't reorder old ones. rule in new ones, don't reorder old ones.
- **Names.** What a thing means, not what it is made of: `naturalLayout$`, not - **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 ## TypeScript, React and RxJS idiom win on a clash