Comments

A comment earns its place only by carrying information the code cannot. Apply this test to every comment you write or read:

If I delete this, does a competent engineer lose something they cannot readily infer from the code?

If no, delete it. Prefer fixing the name or the structure over explaining it.

Delete

• Restatements of the next line or block.
• The purpose of a clearly named variable, function, component, prop or state.
• Straightforward control flow ("loop over rows", "bail out if empty").
• Section banners: // ── Render ──, # ---- helpers ----, {/* Actions */}, # 1. fetch / # 2. transform.
• Anything a type, name or signature already says.
• Standard framework behaviour: what useEffect does, what a Radix primitive renders, how React Query caches, what a DRF ViewSet is, what @shared_task does.
• History: what a change fixed, what used to be there, how many call sites there once were, PR numbers, incident dates. Gravestones for deleted code go with it.
• Plan-phase labels — P0, Phase N, WS-H, Fork 3, Gap 2 — in code, comments, test names and filenames alike.
• JSDoc or a docstring that only re-spells the export name.

Keep, compressed to one or two lines

• A non-obvious design decision, and why.
• A workaround for a framework, browser, API or third-party limitation.
• An edge case, anomaly, or intentionally counterintuitive behaviour.
• A performance, security, contrast, compatibility or correctness constraint.
• An external invariant: a backend contract, a wire format, a required ordering, a provider limit, a token the design system pins.
• A trap where the obvious simplification breaks something.
• Why an empty catch {} / except: pass / no-op guard is deliberate.

Write WHY, not WHAT. Never grow a short useful comment into prose.

Large blocks

Multi-paragraph module headers and JSDoc essays are the main offender. Do not tidy them — delete them, and keep only the constraint they contained. A module named colors.ts exporting TONE_CHIP does not need six paragraphs saying it is about colour. Turning a 20-line essay into a 15-line essay is a failure: it collapses to a line or two, or it goes.

Python specifics

A docstring is not automatically safe — judge it like a comment. Delete one that only re-spells the name ("""Serializer for EvalRun."""), and delete Args/Returns blocks that restate typed parameters. Keep a parameter line only for a unit, a range, an ownership rule or a caller obligation the type cannot express.

Keep, compressed: idempotency and retry expectations on a Celery task, which queue a task must run on, transaction and locking order, and why a write uses .filter().update() — that pattern is deliberate here, it skips signals and leaves the in-memory object stale.

Never remove

biome-ignore, @ts-expect-error, # noqa, # type: ignore, # pragma: no cover, # fmt: off, eslint-*, @vitest-environment, "use client", shebangs, license headers and generated-file banners. Django verbose_name / help_text are UI strings, not comments.

Evaluate each TODO/FIXME on its merits. Keep one that names real outstanding work.

Prompt text inside a string literal is DATA, not commentary. Never edit inside a string, f-string or triple-quoted block that is assigned, returned or passed as an argument, however much it reads like prose.

Two local traps

• frontend/scripts/check-design.sh greps source TEXT, comments included. A comment containing a banned literal (uppercase, page-title) fails the build. Reword it.
• A DRF view docstring becomes the OpenAPI operation description. Deleting one changes the generated client, so prefer an explicit @extend_schema(summary=...).

End state

Very few comments. A well-written file may legitimately have none. Do not keep a comment because having some feels safer, and do not strip a load-bearing constraint to lower the count.