long-paragraph (SMP002)¶
Flags comment paragraphs longer than 100 words by default, since a paragraph that long usually mixes topics and gets skimmed.
Why is this bad?¶
A paragraph that long usually covers more than one topic, and readers skim it. Split at a change of topic, each part is easier to find and to keep accurate.
Example¶
1# Manifests are cached by path and modification time, because parsing them dominates the start-up time of large
2# projects. An entry written by one interpreter is not valid for another, since the parsed form depends on the version
3# of the grammar, so the cache directory is named after the interpreter. Entries older than thirty days are removed on
4# the next run, and a corrupt entry is discarded rather than reported, because the file it came from is still on disk.
5# Writes go to a temporary file first, then replace the entry, so a crash never leaves half of one behind. Readers
6# never lock, since a replaced file is either the old one or the new one.
7CACHE = {}
1# Manifests are cached by path and modification time, because parsing them dominates the start-up time of large
2# projects. An entry written by one interpreter is not valid for another, so the cache directory is named after it.
3#
4# Entries older than thirty days are removed on the next run, and a corrupt entry is discarded rather than reported,
5# because the file it came from is still on disk. Writes go to a temporary file first, then replace the entry, so a
6# crash never leaves half of one behind.
7CACHE = {}
Configuration¶
max-paragraph-wordsin[tool.simplint]: the most words a paragraph may hold, 100 by defaultExample: configuration
pyproject.toml1[tool.simplint] 2max-paragraph-words = 10
1# The cache keeps one entry per manifest, keyed by path and modification time. 2VALUE = 1
What it does¶
No fix is offered, since where to split a paragraph depends on its meaning.
Active on¶
Own-line comment paragraphs: a paragraph is a run of own-line comments on consecutive lines at the same indentation, and it is reported once it passes
max-paragraph-wordswords. Any of these ends it:an empty
#linea line of code
a comment at another indentation
Example: reported and not
Reported
1# The cache keeps one entry per manifest, keyed by path and modification time, because parsing a manifest dominates 2# the start-up time of large projects. An entry written by one interpreter is not valid for another, since the parsed 3# form depends on the version of the grammar, so the cache directory is named after the interpreter. Entries older 4# than thirty days are removed on the next run, and a corrupt entry is discarded rather than reported, because the 5# file it came from is still on disk and can be parsed again. Writes go to a temporary file first, then replace the 6# entry, so a crash never leaves half of one behind. Readers never lock, since a replaced file is either the old one 7# or the new one. 8VALUE = 1
Not reported
1# The cache keeps one entry per manifest, keyed by path and modification time, because parsing a manifest dominates 2# the start-up time of large projects. An entry written by one interpreter is not valid for another, since the parsed 3# form depends on the version of the grammar, so the cache directory is named after the interpreter. 4# 5# Entries older than thirty days are removed on the next run, and a corrupt entry is discarded rather than reported, 6# because the file it came from is still on disk and can be parsed again. Writes go to a temporary file first, then 7# replace the entry, so a crash never leaves half of one behind. Readers never lock, since a replaced file is either 8# the old one or the new one. 9VALUE = 1
Exceptions¶
Trailing comments: a comment after code annotates that line, so it is not part of a paragraph.
Example: not reported
1VALUE = 1 # The cache keeps one entry per manifest, keyed by path and modification time, because parsing a manifest dominates the start-up time of large projects. An entry written by one interpreter is not valid for another, since the parsed form depends on the version of the grammar, so the cache directory is named after the interpreter. Entries older than thirty days are removed on the next run, and a corrupt entry is discarded rather than reported, because the file it came from is still on disk and can be parsed again. Writes go to a temporary file first, then replace the entry, so a crash never leaves half of one behind. Readers never lock, since a replaced file is either the old one or the new one.
Report range¶
The report spans from the paragraph’s first line to the line where it passes max-paragraph-words words.