Why this matters
Prevents drift and misuse by readers and static tools.
Docstrings must match parameter names, optional defaults, return type, and raised exceptions; update the docstring in the same PR as any signature change.
Prevents drift and misuse by readers and static tools.
Side-by-side examples engineers can pattern-match during review.
def find(name: str, limit: int = 10) -> list[str]:
"""Find items.
Args:
query (str): Search query.
limit (int): Required.
"""
...def find(name: str, limit: int = 10) -> list[str]:
"""Find items by name.
Args:
name (str): Case-insensitive filter.
limit (int, optional): Max results. Defaults to 10.
Returns:
list[str]: Matching names.
Raises:
ValueError: If limit <= 0.
"""
...def foo(x: int, y: int = 0) -> int:
"""Add x and y (default 0).
"""
return x + ydef foo(x: int, y: int = 0) -> int:
"""Add a and b.
"""
return x + yFrom the same buckets as this rule.