Python · maintainability
no-long-comment
python:no-long-comment Long docstrings must use deliberate documentation structure or technical anchors.
- Code
- SARJ091
- Default
- error
- Fix
- none
- Languages
- python
Why
An unstructured prose wall is difficult to scan and often hides a contract that belongs in clearer code or durable structured documentation.
Fix
Clarify the code or restructure the docstring with paragraphs, lists, code, paths, links, or other meaningful technical anchors.
Before / after
Executed by this rule’s unit tests.
Before
Eight-sentence prose wall
"""One fact. Two facts. Three facts. Four facts. Five facts. Six facts. Seven facts. Eight facts."""
After
Long documentation split into paragraphs
"""One fact. Two facts. Three facts. Four facts.
Five facts. Six facts. Seven facts. Eight facts.
"""
Limits
- The warning threshold is eight sentence units and applies only to module, private-class, and untyped or private-function docstrings.
- Typed public APIs, runtime-consumed schemas and prompts, generated files, typed sections, and structured documentation are excluded.