Когда описывать параметр функции

Параметр функции следует описывать, когда его назначение или поведение неочевидны из названия, либо когда он имеет особые требования (например, допустимые типы, диапазоны значений или побочные эффекты). Используйте docstring в формате Google, NumPy или reST.

Пример с Google-стилем:

def calculate_area(radius: float) -> float:
    """Вычисляет площадь круга по радиусу.

    Args:
        radius (float): Радиус круга (должен быть положительным).

    Returns:
        float: Площадь круга.

    Raises:
        ValueError: Если радиус отрицательный.
    """
    if radius < 0:
        raise ValueError("Радиус не может быть отрицательным")
    return 3.14 * radius ** 2

Особенно важно документировать:

• Сложные параметры
• Параметры с неявными ограничениями
• Параметры, влияющие на поведение функции неочевидным образом