No code comments

Installation

pnpm dlx shadcn@latest add @aura/rule-no-comments

Why

Agents replicate the patterns already in a file. A comment that explains a temporary workaround makes the hack look sanctioned, so the next change adds "just one more workaround" beside it. The comment then goes stale while the hack spreads.

What to do instead

• MUST: Fix the root cause from first principles so neither the hack nor its comment remains.
• MUST: Express intent through names, types, and tests. Extract a well-named function or constant instead of explaining a block.
• MUST: Encode "do not remove" or "keep this shape" constraints as a type, a test, or a lint rule, not a comment.
• MUST NOT: Leave TODO, FIXME, HACK, or commented-out code.
• MUST NOT: Add a lint or TypeScript suppression to make a workaround pass. An unjustified suppression is a workaround.

Triage an existing comment

• Delete outright when it narrates the code, restates a name, or is stale.
• Solve by refactor when it explains a workaround in our own code. Fix it in the same change when the fix is small. Otherwise record the file, the workaround, and the proposed refactor in the PR, then delete the comment.

Allowed comments

• An external constraint this repo cannot change: a browser quirk, a third-party or library bug, or a platform or spec limit. State the external reason, for example "iOS Safari zooms inputs under 16px".
• Functional directives: 'use client', 'use server', /// <reference …>, JSDoc types in plain JS, @deprecated, and @ts-expect-error / eslint-disable only when the code cannot pass without them, with the reason.
• License headers.
• Generated code. Regenerate it from its source; do not hand-edit it.