A0010 stop-gap-comments¶
Rule: Comments carry no stop-gap markers: TODO, HACK, for now, workaround.
| Code | A0010 (stable, never reused) |
| Id | stop-gap-comments |
| Category | stop-gap |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | deny |
no stop-gaps: a TODO or a 'for now' names its tracker id or goes |
| ai | deny |
a TODO or a 'for now' marks a path the final design throws away; tracked work names its id |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
markers |
list of strings | ["TODO", "XXX", "HACK"] |
markers matched as whole words, case-sensitive; FIXME is fixme-before-land's |
phrases |
list of strings | ["for now", "hack", "workaround", "shim", "quick fix", "temporary fix", "temporary solution", "temporary workaround", "temporary hack", "temporary code", "temporary implementation", "temporary patch", "is temporary", "temporarily disabled", "fix later", "refactor later", "clean up later"] |
phrases matched as whole words, case-insensitive |
tracked-ok |
boolean | true |
a comment with a tracker id (CFG-3), an issue number (#12) or a URL is tracked work and passes |
docs |
boolean | true |
also check doc comments |
Why¶
The top rule of agent-written code: no stop-gaps. A TODO, a HACK or "for now" marks a second path that the final design throws away, and agents leave them by the dozen. A marker that names planned work (TODO(CFG-3), an issue link) is tracked and passes.
FIXME is not a stop-gap here: it is a note to revisit before the branch lands, and fixme-before-land refuses it at the landing.
The rule checks every comment of the workspace members, doc comments included (docs):
markersmatch as whole words, case-sensitive (TODO, not "a todo list");phrasesmatch as whole words, case-insensitive.
"temporary" alone is no stop-gap: it describes the domain as often as the code ("a temporary buffer for the 2 ms burst"). The default list only names phrases about the code itself: "temporary fix", "is temporary", "temporarily disabled".
// TODO: handle errors properly <- reported
// TODO(CFG-3): include keys <- tracked, passes
// hold the line low for a temporary 2 ms reset pulse <- passes
How to fix¶
Build the final version now. Or name the planned work: a FEATURES.md id or an issue link in the comment.
Configure¶
[lints.stop-gap-comments]
level = "deny"
markers = ["TODO", "XXX", "HACK"]
phrases = ["for now", "hack", "workaround", "shim", "quick fix", "temporary fix", "temporary solution", "temporary workaround", "temporary hack", "temporary code", "temporary implementation", "temporary patch", "is temporary", "temporarily disabled", "fix later", "refactor later", "clean up later"]
tracked-ok = true
docs = true
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(stop-gap-comments) <reason> (waivers); the code works there too, as in [lints.A0010].