Skip to content

D0016 reading-ease

Rule: A guide reads easily: short sentences of short words.

Code D0016 (stable, never reused)
Id reading-ease
Category words
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn long sentences of long words are read slowly and understood less
small-workspace warn long sentences of long words are read slowly and understood less
medium warn long sentences of long words are read slowly and understood less
big warn long sentences of long words are read slowly and understood less
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
min-score number 30 the lowest Flesch reading ease a page may score (0 hard, 100 easy)
min-sentences integer 10 sentences from which a page is judged
pages one of "all", "guide", "reference" "guide" the kinds of page judged

Why

Long sentences of long words are read slowly and understood less. The Flesch reading ease score measures both: 206.835 - 1.015 × words per sentence - 84.6 × syllables per word. Plain English scores 60 to 70, technical writing 30 to 50, and under 30 most readers need several passes.

The score is an estimate: syllables are counted by a spelling heuristic, and names and code in the prose lower it. spl pages shows each page's score. Pages with fewer sentences than min-sentences are not judged, and only pages in English.

How to fix

Split long sentences: one idea each. Use the short word where it says the same, "use" for "utilise", "start" for "initialise". Move lists of names and options into a list or a table, where they are not prose.

Configure

[lints.reading-ease]
level = "deny"
min-score = 30
min-sentences = 10
pages = "guide"
reason = "why this project wants it at this level"

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