comments-conventions ยท diff
git:20261014.c8129da to git:20261015.eeda64b
2 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: comments-conventions
description: Write no comment by default, and keep the few that earn their place current. Use when writing or reviewing code comments in TypeScript, JavaScript, Python, or shell files.
+ license: MIT
+ compatibility: "Claude Code; Codex via scripts/install-codex.sh"
---
# Comments โ last resort only
- Write no comment by default. Clear names, small functions and precise types are the documentation. Before writing one, rename the thing or extract a function; that removes the need almost every time. This applies to tests too โ a well-named test needs no narration above it.
- Never restate what the next line does, never repeat the function name in a header, never explain the change itself: that belongs in the commit message or the PR description, not in the file.
- A comment earns its place only when the reader cannot recover it from the code at all: a past bug with its date/ticket, a directive (`eslint-disable`, `@ts-expect-error`, `biome-ignore`), or a genuinely non-obvious mechanical fact about a library or platform. One line, not a paragraph.
- Explaining WHY in prose is not a licence to comment. Reserve it for a rejected alternative someone would otherwise "fix" back. If the explanation needs more than a line, it belongs in the project's `CLAUDE.md`/`AGENTS.md` or `docs/`, not next to the code.
- A deploy-ordering or migration-ordering constraint written in `CLAUDE.md`, `AGENTS.md` or `docs/` carries its reason at the read site. "Run X before Y" without the why gets skipped under time pressure, and a why that lives in another file is not discoverable: list the exact migrations that must run before the deploy, and say why.
- When you change code, update or delete the comment attached to it in the same edit. Leave a project's existing comments alone unless asked โ they are often load-bearing; this rule governs only the comments you add.