P0016 thinking-comments¶
Rule: Comments state conclusions, not a stream of thought.
| Code | P0016 (stable, never reused) |
| Id | thinking-comments |
| Category | prose |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | deny |
a comment holds the conclusion, not the reasoning that led to it |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
phrases |
list of strings | ["hmm", "wait,", "actually,", "i think", "i guess", "not sure", "let's see", "ok so", "okay so", "oops", "on second thought", "i wonder"] |
the phrases, matched as whole words, case-insensitive |
questions |
boolean | true |
also report comments that end with a question mark |
Why¶
A comment is read many times; it should hold the conclusion. "Hmm", "actually,", "I think" and open questions are the writer thinking aloud, often an agent's reasoning left in the code. They leave the reader to finish the thought.
The rule checks non-doc comments (//, /* */) for the phrases, and with questions on, for a comment that ends with ? (URLs excepted).
How to fix¶
Decide, and write the decision as a statement. An open question goes into FEATURES.md or an issue.
Configure¶
[lints.thinking-comments]
level = "deny"
phrases = ["hmm", "wait,", "actually,", "i think", "i guess", "not sure", "let's see", "ok so", "okay so", "oops", "on second thought", "i wonder"]
questions = true
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(thinking-comments) <reason> (waivers); the code works there too, as in [lints.P0016].