Skip to content

P0015 sentence-words

Rule: Sentences in docs stay short.

Code P0015 (stable, never reused)
Id sentence-words
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 short sentences are read once and understood
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
max-words integer 25 words a sentence may have
files list of strings ["**/*.md"] globs of the Markdown files checked, relative to the root
skip list of strings [] globs of Markdown files left out

Why

Long sentences are where readers lose the thread. Agents write them by joining clauses with commas and "which". Short sentences are read once and understood.

Paragraphs and list items of the Markdown files in files are split into sentences after ., ! or ? followed by a space (not after abbreviations like e.g., single letters or numbers). Headings, tables, quotes and code are not checked. A sentence with more than max-words words is reported.

How to fix

Split it. Cut what changes nothing for the reader. Make several facts a list.

Configure

[lints.sentence-words]
level = "deny"
max-words = 25
files = ["**/*.md"]
skip = []
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(sentence-words) <reason> (waivers); the code works there too, as in [lints.P0015].