Skip to content
Sarj Standards

Python · maintainability

docstring-args-restate-signature

python:docstring-args-restate-signature

Argument documentation must add facts beyond the function signature.

Code
SARJ086
Default
error
Fix
none
Languages
python

Why

Repeating parameter names and types obscures useful behavioral contracts and drifts when signatures change.

Fix

Remove the redundant argument section, or retain it only to document constraints, units, defaults, or semantics absent from the signature.

Before / after

Executed by this rule’s unit tests.

Before

Argument description repeats its name

app/widgets.py · focus
def count_widgets(tenant_id: str) -> int:
    """Count active widgets.

    Args:
        tenant_id: Tenant ID
    """
    return 0

After

Argument description records a unit

app/widgets.py · focus
def set_timeout_ms(timeout_ms: int) -> None:
    """Configure the request deadline.

    Args:
        timeout_ms: Timeout in ms
    """

Limits

  • The rule reads Google-style argument sections and requires every documented entry to be a restatement before reporting.
  • Generated files, runtime-consumed prompt, CLI, and route docstrings, protected facts, and empty machine-generated stubs are excluded.