---
title: "No comments"
description: "Code comments are banned because names, types, tests, and boundaries should carry the meaning."
sources:
  - https://github.com/joelhooks/rat-stack/blob/main/AGENTS.md
  - https://github.com/joelhooks/rat-stack/blob/main/scripts/oxlint-plugin-no-comments.ts
---

The code rule bans prose comments because agents copy them, and a comment that explains a workaround can spread the workaround. Put the reason where the code can enforce or reveal it: in a name, a type, a test, a commit message, or the Brain.

Three forms remain. Tool directives can suppress a specific diagnostic when the reason follows `--`, as in `// oxlint-disable-next-line rule -- reason`. A one-line `SAFETY:` invariant can sit above a type assertion and name what makes it safe. Plain JavaScript can keep JSDoc blocks made only of type tags, because those tags provide type syntax. TypeScript's comment directives also need an inline reason, and the configured lint rule decides which directives may stay.

Before running `pnpm fix`, harvest any meaning a comment carries. `--fix` can delete prose comments, and losing the reason while retaining the workaround is exactly the wrong cleanup. Move it into the symbol, type, test, commit, or Brain note first.

See [the fence](/lore/the-fence) for how the rule is enforced and [tests that earn their place](/lore/tests-that-earn-their-place) for the test that can replace a comment.