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