Skip to content
Sarj Code Standards

no-unnecessary-docstring

No docstring consumer detected — delete it; make author-controlled names, types, and structure explain the code.

SARJ420 Rule source Tests Catalog JSON

Why

A docstring with no detected consumer makes code depend on prose for ordinary meaning and creates a second maintenance surface that agents expand and maintainers must review.

Fix

Delete the docstring. If author-controlled code is unclear without it, clarify names, types, and structure or extract a small named helper. Keep a genuinely hidden invariant as one concise local comment. When external tooling consumes __doc__, use an exact SARJ420 suppression that names the consumer.

Examples

Before — flagged A wrapper excluding __doc__ does not consume input prose
app/metadata.py
from functools import wraps




def original() -> int:
    """This prose is not copied."""
    return 1




@wraps(original, assigned=())
def wrapped() -> int:
    return original()
After — preferred A cache wrapper copies the function's documentation
app/metadata.py
from functools import lru_cache




@lru_cache(maxsize=1)
def count() -> int:
    """Copied onto the wrapper."""
    return 1
Before — flagged Human-only module, class, and function prose
app/service.py
"""Service entry points."""




class Service:
    """Coordinates requests."""


    def run(self) -> None:
        """Run the service."""
        return None
After — preferred Framework consumes the function docstring
app/tools.py
from agents import function_tool




@function_tool
def lookup_account(account_id: str) -> str:
    """Look up an account for the model."""
    return account_id
Before — flagged Unconsumed top-of-file prose is deleted
app/service.py
"""Service entry points.


Coordinates requests.
"""


VALUE = 1
After — preferred A module description consumed at runtime is retained
app/service.py
"""Service entry points."""


DESCRIPTION = __doc__
Autofix output
app/service.py
VALUE = 1