---
paths:
  - "**/*.{ts,tsx,js,jsx,mjs,cjs,py,rs,go,sol,sh,bash,zsh,rb,lua,zig,nix,ex,yaml,yml,toml}"
---

## Code comments

Budget: 1-3 lines. Write one only when an agent with the repo and thirty
seconds of grep would still get it wrong. That means one of:

- something that breaks silently — no test catches it, or a caller can
  break it from outside
- a fact not in the repo (deployed bytecode, chain quirk, library bug)
- a unit or epoch the type cannot carry (wei, ms, 18-dp)

Good:

> `// MUST read lastGoodPrice before fetchPrice — same eth_call state.`

Everything else: delete. Design rationale and rejected alternatives go in
`docs/`; leave a path. History is in git. No emphasis; ALL-CAPS only for
MUST / NEVER.

Deleting a comment is cheap and reversible. When unsure, delete.

### Doc comments are not this

Rustdoc `///`, JSDoc `/** */`, Solidity NatSpec `@notice`/`@dev`, Python
docstrings: different genre, budget does not apply. They document a surface
for callers who cannot see the body, and tooling reads them — NatSpec ends
up in contract metadata. Follow the language's convention, and never strip
them to satisfy the budget above.