Lean Comments

Goal

Keep the smallest amount of high-value commentary necessary to make a codebase easier and safer to understand and maintain.

The default is no comment.

A comment must preserve meaningful information that a competent maintainer cannot reasonably recover from the code, names, types, signatures, structure, tests, configuration, or nearby context.

Comments are not labels, narration, decoration, declaration summaries, change logs, or substitutes for clear code.

Reader model

Write for a competent maintainer reading the repository at HEAD months later, without access to the current conversation, prompt, diff, pull request, issue discussion, review discussion, or implementation process.

Document the durable state, contract, constraint, or rationale of the code as it exists. Do not assume the reader knows what changed, what came before, or what was discussed unless that context is deliberately preserved in a reliable project source.

Authority and evidence

Use this skill as the comment-policy authority when it is active.

Use language, framework, library, or infrastructure skills to determine whether a non-obvious constraint is real, not to override this skill's necessity test.

Honor explicit current repository requirements, public API documentation requirements, tooling contracts, and generated-source rules. Do not infer a documentation requirement merely from existing comment density or precedent.

Base retained or newly written rationale on evidence from the repository, tests, configuration, official API behavior, project documentation, issue tracker, ADRs, specifications, or another reliable source.

Never invent a security reason, performance reason, business rule, compatibility requirement, API constraint, historical reason, architectural rationale, or external limitation to justify commentary.

If no supported non-obvious reason exists, remove or omit it.

Core decision rule

Before retaining or adding ordinary commentary, mentally remove it and ask:

Would a competent maintainer lose meaningful, non-obvious information if this comment did not exist?

If no, remove or omit it.

If uncertain, prefer no comment unless repository evidence demonstrates that the information matters.

If yes, retain only the minimum information necessary.

Never preserve a comment merely because it is correct, harmless, already present, grammatically polished, written as a warning, related to security or validation, related to internal or public state, or attached to an exported declaration.

The information itself must justify the comment.

Decision order

Evaluate existing and proposed commentary in this order:

1. Delete or omit if the information is already clear without it
2. Express through code if a tiny behavior-preserving readability improvement removes the need for it
3. Shorten if it is necessary but contains unnecessary information or words
4. Rewrite if it is necessary but unclear, inaccurate, stale, awkward, or inconsistent
5. Use declaration documentation if the information belongs to the declaration's contract, semantics, or intended usage
6. Keep unchanged only if it is already necessary, minimal, accurate, durable, and correctly styled

Always decide necessity before wording.

Do not polish an unnecessary comment or convert one into documentation.

What deserves an implementation comment

Use an implementation comment when it preserves non-obvious information such as:

• Why intentionally surprising code exists
• An external constraint or compatibility requirement
• An important invariant or subtle edge case
• A meaningful tradeoff or required workaround
• Non-obvious coupling
• An ordering, timing, lifecycle, concurrency, performance, or security constraint
• A reason an apparently simpler implementation would be incorrect

Prefer comments that explain why something matters.

Comments that merely explain what the code does should normally be removed.

Remove low-value commentary

Remove comments that merely:

• Restate or translate the code into prose
• Narrate the next statement or obvious control flow
• Explain an obvious guard clause, return, assignment, or branch
• Describe an obvious fetch, validation, transformation, mapping, filtering, creation, update, or deletion
• Repeat a declaration name, property name, type, signature, parameter, or return type
• Label or summarize a declaration

…