commenting-code

Writes and reviews code comments that preserve non-obvious intent, contracts, invariants, and failure semantics without narrating the code. Uses clear layer placement (interface, implementation, cross-module) and lightweight review checks to keep comments accurate over time. Use when adding or reviewing inline comments, docstrings, API docs, or design notes for behavior that could be misunderstood.

Commenting Code

Core principles

  • Improve naming and structure first; do not comment around unclear code.
  • Add comments only when they prevent a likely misunderstanding.
  • Prefer stable intent over volatile implementation narration.
  • Keep comments concise, concrete, and testable.

Workflow

  1. Decide whether a comment is needed. Add a comment when behavior could be misread and lead to defects (for example: invariants, ordering constraints, concurrency assumptions, retries/timeouts, side effects, or error semantics).
  2. Choose the right layer.
    • Interface docs: caller-visible contract and usage semantics.
    • Implementation comments: maintainer-facing rationale and invariants.
    • Cross-module notes: decisions that span module boundaries.
  3. Write the smallest high-signal comment. Lead with the most important fact. Include concrete details (units, bounds, ordering, failure behavior) when relevant.
  4. Remove low-value comments. Delete tautologies, stale comments, hedging, and commented-out code.
  5. Keep docs synchronized with behavior. If behavior changes, update comments/docs in the same change.

What to include

Interface docs (caller-facing)

Document what callers can rely on:

  • behavior guarantee
  • input constraints and units
  • return semantics (including edge cases)
  • error/failure semantics
  • side effects and mutation behavior
  • concurrency or idempotency semantics when relevant

Implementation comments (maintainer-facing)

Document what maintainers must preserve:

  • why this approach exists
  • invariants and assumptions
  • non-obvious failure/retry behavior
  • coupling constraints that can break correctness

Cross-module notes

For decisions spanning modules, keep one central design note and add a short local pointer from affected modules.

Precision checklist

Apply this to interface and non-trivial implementation comments:

  • Are units explicit (ms, bytes, etc.)?
  • Are bounds/ranges clear (inclusive vs exclusive)?
  • Are null/empty/zero semantics explicit?
  • Are ownership/lifecycle expectations clear?
  • Are invariants stated precisely?
  • Are failure and retry semantics unambiguous?

Anti-patterns to remove

  • Restating obvious code steps
  • Stale comments that contradict behavior
  • Hedging language (for example: "might", "probably", "should work")
  • Ownerless TODO/FIXME notes
  • Commented-out code and journal-style history notes
  • Over-commenting that buries important context

Minimal templates

Interface doc template

Summary:
Inputs:
Returns:
Errors:
Semantics:

Implementation comment template

Why:
Invariant:
Assumption:
Failure mode:

Review bar

Treat documentation correctness like code correctness:

  • block changes when contract-relevant behavior changed but docs did not
  • block comments that contradict actual behavior
  • request cleanup when narration can be replaced by clearer naming