comments-conventions · git:20261015.933b000 · 2026-10-15 · sha256 d8df4d5f23ff3e4a
comments-conventions git:20261015.933b000A
Immutable. This exact content never changes and is served at /api/v1/blob/d8df4d5f23ff3e4a.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_y2gcfdvzvqi4v7rp/d8df4d5f23ff3e4ae178e2f7aa4ac6fa26955f24e8b5fb4a861df9f98a3b261a.json
Then /plugin install comments-conventions@markdownregistry-y2gcfdvzvqi4v7rp in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- 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. - 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.