code-comments

Code Comments (mandatory)

Default to no comment. Code, names, and tests carry intent. A comment must justify its existence.

Why this exists

AI agents wrote comments asserting program behavior that the code did not perform. False or stale comments mislead reviewers and hide defects.

Principle

A comment is a sign of failure to write clear code. Use it only when the why is non-obvious — never to narrate what the code does. If you cannot express the intent in code (names, test names, a smaller function), add a comment explaining the constraint or choice. When the comment is gone, the intent should also be gone from the reader's expectation.

Forbidden comment classes

• Narrating what the code does: // Set the flag to true, // Increment counter, // Call the API, // Parse the JSON. If the code is unclear, rename it; don't narrate it.
• Restating signatures or type names: // userId is a Guid, // Returns a list of customers, // The account ID. These repeat what the type system already states.
• Referencing the task, PR, ticket, agent, or brief: // As requested in AB#1234, // This is for the catalog feature, // Agent asked for this. That belongs in the commit message, not the code.
• Restating ADR/rule content (adr-restate): Paraphrasing or quoting ADR sections, points, phases, or AGENTS.md / .claude rules / CLAUDE.md. Citations must be bare pointers only ((ADR-NNNN) or (RFC 7636 §4.2) for external specs — section allowed for RFCs only). Example: WRONG: // ADR-NNNN point 2 — grant TTL for password reset; GrantTimeToLive must…; RIGHT: // Short grant TTL limits leaked reset link window (ADR-NNNN).
• Requirement or work-item IDs (task-ref): // US123, // EX456, // SEC789, // R42, // F3b, // #12345, // WI 99, // TC #42, // Phase 3, // P1.2, // Pin #7. Strip the ID; keep the sentence if a why remains. Example: WRONG: // US123 — validate email format; RIGHT: // Validate email format (already handles unicode per spec) or just delete if no why.
• Changelog or history comments: // Removed the old filter logic, // Now uses EF Core instead of Dapper, // Previously called PaymentService, // Fixed the bug where…, // Refactored to…, // Updated to…. Commit history is the changelog.
• Quality or verification claims: // Tested thoroughly, // This is thread-safe, // Guaranteed to handle all cases, // Fully covered by tests, // Safe because…. If the claim is true, the code proves it or tests prove it; if you need to assert it, you doubt the code.
• Commented-out code: Never. Use git history instead.
• Section banners, #region, or delimiters: // ===== Customers =====, // TODO: Payments, #region Invoice logic.
• Lint/analyzer suppressions without reason: // eslint-disable, @ts-ignore, #pragma warning disable alone. Always include why: // eslint-disable-next-line no-console — debug output for AB#1234.
• Bare TODO or FIXME: Always include a ticket: // TODO(AB#1234): Add validation.