---
description: Never comment in code except TODO/FIXME/XXX or deletion warnings
alwaysApply: true
---

# Comments

- Never add comments in code by default.
- Prefer clear names and structure so the code needs no explanation.
- Do not narrate what the code already says.
- Do not add JSDoc, section banners, or "why/how" comments for ordinary logic.
- Comments are allowed only for these purposes:
  1. `TODO` — unfinished work that must be tracked in-code
  2. `FIXME` — known broken or incorrect behavior that must be fixed
  3. `XXX` — dangerous / surprising hazard that a reader must not miss
  4. Deletion caution — warn why removing a line or block would break something non-obvious
- Keep allowed comments one short line when possible.
- Match nearby file style: if the surrounding code has few comments, keep it that way.