Skip to content
Sarj Standards

Python · maintainability

docstring-returns-restate-signature

python:docstring-returns-restate-signature

Return documentation must add facts beyond the function name and annotation.

Code
SARJ087
Default
error
Fix
none
Languages
python

Why

Repeating the return type or function name adds noise and can become stale without explaining the result's semantics.

Fix

Remove the redundant return section, or document identity, units, constraints, or other behavior absent from the signature.

Before / after

Executed by this rule’s unit tests.

Before

Return description repeats the signature

app/lines.py · focus
def get_line_length(line: list[str]) -> int:
    """Measure a rendered line.

    Returns:
        int: The length of the line.
    """
    return len(line)

After

Return description records semantics

app/lines.py · focus
def get_line_length(line: list[str]) -> int:
    """Measure a rendered line.

    Returns:
        The width in terminal cells, which is not the character count.
    """
    return len(line)

Limits

  • The rule reads Google-style return and yield sections and uses conservative signature-word matching.
  • Generated files, runtime-consumed docstrings, protected facts, identity semantics, and whole-docstring restatements owned by SARJ050 are excluded.