comment-conventionslisted
Install: claude install-skill rvanbaalen/skills
# Comment Conventions
Language-agnostic rules for writing code comments and docblocks. They apply to any language and any comment syntax — inline `//`, block `/* */`, JSDoc, TSDoc, PHPDoc, Python docstrings, Rustdoc `///`, GoDoc, KDoc, Elixir `@doc`, Ruby YARD, etc.
These rules govern *how* a comment is written when one exists, plus *when* a docblock is required. They do not push for more comments overall — terse, well-named code with no inline comments is still preferred.
## Rule 1 — Comments describe what is, not what was
Comments live in the present tense of the current implementation. The reader is asking "what does this do?" — they don't care that an earlier version did something else.
**Wrong** — narrates implementation history:
```js
// We used to use a Map here but it didn't preserve insertion order
// reliably across runtimes, so we switched to an array of tuples.
const entries = [];
```
**Right** — describes what the code does now:
```js
// Stored as tuples to preserve insertion order.
const entries = [];
```
The exception: reference past context only when the *reference itself* adds explanation a developer would want today — typically a ticket, RFC, ADR, or commit hash that has the full story.
**OK** — pointer adds value:
```js
// Tuple form required by the upstream consumer; see issue #123.
const entries = [];
```
Why this matters: implementation history rots. A reader two years from now sees no trace of the "old way" — the comment becomes archaeologic