Lean Comments

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
• Repeat information already represented clearly by tests or configuration
• Add generic context that is immediately inferable
• Act as unnecessary section headings or visual separators
• Preserve obsolete change history
• Address the reviewer or justify the current change
• State a bare rule or prohibition without useful non-obvious context
• Add rhetorical emphasis without information

Words such as Never, Always, Important, Security, Internal, Public, or Required do not make a comment valuable.

Judge the information, not how serious the wording sounds.

Prefer self-explanatory code

When a comment compensates for unnecessarily confusing code, consider a tiny local behavior-preserving improvement such as improving a local name, extracting a clearly named boolean, simplifying local control flow, or removing redundant local structure.

Keep such changes minimal and directly related to clarity.

Do not turn comment cleanup into a general refactor or change behavior, architecture, public APIs, dependencies, or unrelated code merely to eliminate comments.

Comment and documentation forms

Apply the same necessity test across languages and syntaxes.

Relevant forms may include:

• Line and block comments such as //, #, --, and /* ... */
• JSDoc, TSDoc, JavaDoc, KDoc, Rust doc comments, Go doc comments, C# XML documentation, and equivalent declaration documentation
• Module, package, and file documentation
• Python docstrings and other declaration documentation represented as runtime-visible strings
• TODO, FIXME, NOTE, HACK, XXX, and similar markers
• Tooling, compiler, formatter, coverage, build, framework, generator, and machine-consumed directives

Do not treat comment-like text inside string literals, regular expressions, URLs, snapshots, fixtures, templates, or test data as source comments merely because it contains comment syntax.

Implementation comments

Use the language's normal implementation-comment form for brief rationale, constraints, invariants, workarounds, or other non-obvious local context.

Prefer one concise line when one line is sufficient.

Declaration documentation

Use the language's declaration-documentation form only when the information belongs to the declaration itself and forms part of its contract, semantics, or intended usage.

For TypeScript, use TSDoc-compatible documentation when warranted. For JavaScript, follow intentional repository JSDoc conventions. For other languages, follow the language and repository's real documentation conventions without creating coverage for its own sake.

Module and file documentation

Add module, package, or file-level documentation only for a durable architectural concept, boundary, invariant, terminology, lifecycle rule, or design rationale that is not apparent from the contents.

Do not add file headers that merely summarize exports or describe an obvious file purpose.

Runtime-visible documentation

Some documentation forms, especially Python docstrings, can be observable at runtime through introspection or tooling.

Before removing or materially changing runtime-visible documentation, verify that doing so does not change a supported runtime contract, generated documentation surface, or external API expectation.

Declaration documentation rules

This is not a documentation coverage exercise.

Do not document declarations merely because they are exported or public, and do not assume every language-level export in application code is an intentionally supported external API.

Use declaration documentation when consumers or maintainers need non-obvious information about:

• Behavioral contracts, parameter constraints, return semantics, or special values
• Error behavior, side effects, preconditions, or postconditions
• Ordering, timing, lifecycle, concurrency, or caching behavior
• Security, runtime, server, client, SSR, or environment constraints
• Compatibility requirements or upstream API behavior
• Business rules or invariants
• Units, formats, ranges, encodings, or cross-field relationships
• Deprecation, extension points, or important usage restrictions
• Non-obvious usage that materially benefits from an example

Apply a stronger documentation bias to published libraries, SDKs, packages, plugins, extension APIs, and intentionally external interfaces.

Apply a stronger no-documentation bias to internal helpers, simple CRUD methods, straightforward adapters, composables, plain data shapes, DTOs, and internal utilities.

Do not repeat the type system

Do not add documentation that merely restates names, types, signatures, obvious values, or structure already expressed by the language.

Do not mechanically add tags such as @param, @returns, @throws, @example, @remarks, or @see. Use a tag only when it contributes information beyond the declaration and type system.

Plain interfaces, records, DTOs, structs, types, and obvious data shapes normally require no documentation unless they contain non-obvious semantics, invariants, formats, units, relationships, external constraints, or compatibility requirements.

Style

Single-line prose implementation comments

For a necessary single-line prose implementation comment, regardless of comment delimiter:

• Keep it as short as possible without making it cryptic
• Start normal prose with an uppercase letter unless technically required casing dictates otherwise
• Do not end it with ., !, ?, or other terminal sentence punctuation
• Do not use em dashes or en dashes
• Do not use dash-based sentence punctuation
• Do not use semicolons as sentence punctuation
• Prefer a concise clause over unnecessarily complete prose
• Preserve exact casing and punctuation in identifiers, code, commands, URLs, paths, package names, versions, API values, and other technical literals

Example:

// Preserve source order for positional matching

Not:

// Preserve source order for positional matching.

These prose rules do not apply to machine-consumed syntax, technically significant punctuation, or genuine multi-line declaration documentation.

Declaration documentation

Use normal sentence punctuation for genuine multi-sentence declaration documentation.

Keep it concise and focused on meaningful contract or semantic information. Do not add prose, tags, examples, or sections merely to make documentation appear complete.

High-value examples

<examples>

<example>
Delete:

// A watchlist row
export interface FlickWatchlistItem {
  media: FlickMedia;
  added_at: string;
}

Correct:

export interface FlickWatchlistItem {
  media: FlickMedia;
  added_at: string;
}

The declaration already communicates the concept. Do not shorten the comment or convert it into declaration documentation. </example>

<example>
Usually delete:

// Never copy a raw internal message into the public response

Do not preserve this merely because it contains Never or concerns a public boundary.

If repository evidence establishes a genuinely non-obvious reason, retain only that supported reason:

// Keep provider errors private because messages may contain credentials

Never invent such rationale to save the original comment. </example>

<example>
Delete:

// Return the normalized result
return normalize(result);

The code already communicates the action. </example>

<example>
Keep when supported by the implementation or external contract:

// Preserve source order because the upstream API matches items by position

The comment communicates a non-obvious positional constraint. </example>

<example>
Useful declaration documentation:

/**
 * Returns `null` for private profiles instead of propagating the upstream authorization error.
 */
export async function getProfile(): Promise<Profile | null> {
  // ...
}

The documentation explains caller-visible behavior that the type alone cannot communicate. </example>

</examples>

TODO, FIXME, NOTE, and similar markers

Treat TODO, FIXME, NOTE, HACK, XXX, and equivalent markers as comments, not exceptions.

Verify that each one is still relevant, technically accurate, useful, and actionable when appropriate. Follow repository conventions for issue references or ownership when such conventions actually exist.

Remove stale, completed, meaningless, or superseded markers.

Do not add a marker prefix merely to make an ordinary comment appear important.

Do not implement unrelated work solely to remove a valid marker.