Skip to content
Sarj Sarj Sarj Standards

docstring-args-restate-signature

Remove a wholly redundant Google-style Args section when every entry only repeats the function signature.

SARJ086 Rule source Tests Catalog JSON

Why

Repeated names and types drift and crowd out constraints, units, ownership, and side effects. Complete parameter tables may remain when a public documentation contract requires them.

Fix

Remove only the redundant Args section; remove the whole docstring only when no section adds behavior. Keep constraints, accepted formats, units, non-obvious defaults, relationships, and public API semantics in the docstring.

Examples

Before — flagged Argument description repeats its name
app/widgets.py
def count_widgets(tenant_id: str) -> int:
    """Count active widgets.


    Args:
        tenant_id: Tenant ID
    """
    return 0
After — preferred Unit and sentinel semantics add a contract
app/widgets.py
def set_timeout(timeout_ms: int) -> None:
    """Configure request handling.


    Args:
        timeout_ms: Request deadline in milliseconds; zero disables retries.
    """