Skip to content

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).

// hmm, should this be u32?        <- two findings
// u16: the frame length field is two bytes.

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].