comments-conventions
Write no comment by default, and keep the few that earn their place current.
- Group
- Conventions
- Kind
- Read-only
- Loads when
- Writing or reviewing code comments
When it runs
When code comments are being written or reviewed in TypeScript, JavaScript, Python or shell files. Claude loads it on its own when the description matches the file or the task; it never writes anything itself. It matches:
- TypeScript
- JavaScript
- Python
- Shell scripts
- writing comments
- reviewing comments
The conventions
- No comment by default. Clear names, small functions and precise types are the documentation. Before writing a comment, rename the thing or extract a function; that removes the need almost every time. Tests too: a well-named test needs no narration.
- No restating. Never restate what the next line does, repeat the function name in a header, or explain the change itself; that belongs in the commit message or the PR description.
- When a comment earns its place. Only when the reader cannot recover it from the code: a past bug with its date or ticket, a directive (
eslint-disable,@ts-expect-error,biome-ignore), or a genuinely non-obvious fact about a library or platform. One line, not a paragraph. - WHY is not a licence. Reserve a why-comment for a rejected alternative someone would otherwise "fix" back. If it needs more than a line, it belongs in the project's
CLAUDE.md/AGENTS.mdordocs/. - Keep them current. When you change code, update or delete its comment in the same edit. Leave a project's existing comments alone unless asked; they are often load-bearing. The rule governs only the comments you add.
Related
- typescript-conventions: small, single-purpose functions that need no narration.
- code-review applies the project's conventions when it rates a change.
- Conventions skills in the functional specification.