P0014 restating-comments¶
Rule: A comment says what the code cannot.
| Code | P0014 (stable, never reused) |
| Id | restating-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 | warn |
a comment says what the code cannot |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
min-overlap |
number | 0.75 |
share of the comment's content words found in the next line from which it restates it |
min-words |
integer | 2 |
content words a comment needs to be judged |
max-words |
integer | 8 |
comments with more content words are not judged |
Why¶
A comment that says what the next line says doubles the text and drifts when the code changes. Comments are for what the code cannot say: why, the unit, the invariant, the source of a number.
The measure, per single-line // comment directly above a code line:
- The comment's content words: words of two or more characters, stopwords (
the,a,to,of,this, ...) dropped,snake_caseandCamelCasesplit, lowercased, a plural or-ed/-ingending removed. - The code's words: the identifiers of the next line split the same way, plus words for its operators and keywords (
+=gives increment, increase, add;newgives create, new, make;return,push,len,clone,for,if). - The overlap: the share of the comment's content words found among the code's words.
A comment with between min-words and max-words content words and an overlap of at least min-overlap is reported, with the overlap as its metric.
// increment the counter <- overlap 100%: increment (+=), counter
counter += 1;
// the PLL needs 2 ms to lock <- overlap 25%: passes
delay_ms(2);
How to fix¶
Delete the comment, or replace it with what the code does not show.
Configure¶
[lints.restating-comments]
level = "deny"
min-overlap = 0.75
min-words = 2
max-words = 8
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(restating-comments) <reason> (waivers); the code works there too, as in [lints.P0014].