D0003 heading-words¶
Rule: A heading is a short name, not a sentence.
| Code | D0003 (stable, never reused) |
| Id | heading-words |
| Category | reading |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
headings are scanned to find a section; a sentence is read slowly |
| small-workspace | warn |
headings are scanned to find a section; a sentence is read slowly |
| medium | warn |
headings are scanned to find a section; a sentence is read slowly |
| big | warn |
headings are scanned to find a section; a sentence is read slowly |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
max-words |
integer | 8 |
words a heading may have |
pages |
one of "all", "guide", "reference" | "guide" |
the kinds of page judged |
Why¶
Headings are the page's table of contents. A reader scans them to find the part they need, and the navigation lists them. A short heading that names what the section answers is read at a glance. A heading written as a sentence is read like one, slowly.
## Flashing over USB <- a name
## How to flash the board over USB when the probe is busy <- a sentence
How to fix¶
Name the section in a few words. Move the rest of the sentence into the first paragraph under the heading.
Configure¶
[lints.heading-words]
level = "deny"
max-words = 8
pages = "guide"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(heading-words) <reason> (waivers); the code works there too, as in [lints.D0003].