D0005 code-wall¶
Rule: Code comes with prose that explains it.
| Code | D0005 (stable, never reused) |
| Id | code-wall |
| Category | reading |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
code without prose leaves the reader to guess what it shows |
| small-workspace | warn |
code without prose leaves the reader to guess what it shows |
| medium | warn |
code without prose leaves the reader to guess what it shows |
| big | warn |
code without prose leaves the reader to guess what it shows |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
max-lines |
integer | 60 |
lines of code a reader meets with no prose between them |
pages |
one of "all", "guide", "reference" | "guide" |
the kinds of page judged |
Why¶
Code without prose leaves the reader to work out what it shows and why it is there. A page of listings one after another reads like a source file, and the reader stops at the first block they do not understand.
The lint adds up the lines of code blocks that follow each other with no prose between them. Headings, tables and figures between the blocks do not count as explanation.
How to fix¶
Before each block, say in a sentence what it shows and what to notice. Cut a long listing to the lines that matter, and link the full file. Several variants of one example are clearer as content tabs with a sentence above them.
Configure¶
[lints.code-wall]
level = "deny"
max-lines = 60
pages = "guide"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(code-wall) <reason> (waivers); the code works there too, as in [lints.D0005].