For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/shared/engineering/comments.md.
Quick start

Code comments

Comment on the reason a future reader could miss.

Rationale

Why

An ordering constraint can prevent data loss. Translating a function name into a sentence does not add useful context.

Rules

  • MUST omit comments that paraphrase identifiers or the next statement. [review]
  • MAY explain a workaround, lifecycle constraint, safety invariant, or deliberate compromise. [review]
  • MUST attach a tracked reference to unfinished work. [review]
  • MUST explain the reason for a lint suppression wherever its syntax allows it. [review]
  • MUST preserve tool-maintained markers and required license notices. [review]
  • MUST use modules and declarations instead of decorative comment banners. [review]
  • MUST follow the language pack's public documentation conventions. [review]

[review]

Review establishes whether comments add rationale. Formatters and configured documentation checks cover only their configured syntax.

Enforcement

Review establishes whether comments add rationale. Formatters and configured documentation checks cover only their configured syntax.