Skip to content

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