stale-age

Part of: Freshness Check

Check	freshness
Category	recommended
Applies to	functions, methods, classes
Since	v1.0.0

Docstring untouched beyond age threshold

What it detects

This rule flags symbols whose docstring has not been touched for more than age-threshold days (default: 90), regardless of whether the code changed. It uses git blame timestamps to determine the docstring's last modification date.

Why is this a problem?

Very old docstrings may describe obsolete behavior, outdated APIs, or deprecated patterns — even if the surrounding code hasn't changed much. A periodic review of aging docstrings ensures they remain accurate and relevant as the project evolves.

How to Fix

The docstring has not been updated for longer than the configured age threshold. Review the entire docstring for accuracy — even small wording improvements reset the age counter. Confirm the summary, parameters, return values, and examples still reflect current behavior.

Example

ViolationFix

# Docstring last modified 180 days ago:
def get_connection() -> Connection:
    """Get a database connection from the pool.

    Returns:
        Active database connection.
    """
    return pool.acquire()

# Reviewed and updated (resets the age counter):
def get_connection() -> Connection:
    """Get a database connection from the connection pool.

    Returns:
        Active database connection ready for queries.
    """
    return pool.acquire()