Skip to content

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