Зачем добавлять примеры использования в docstring?

Docstring — это строковая документация, встроенная в код, которая объясняет назначение функции, класса или модуля. Добавление примеров использования в docstring превращает сухое описание в практическое руководство.

Зачем нужны примеры?

• Непосредственная демонстрация: Показывают, как вызывать функцию с конкретными аргументами и что она возвращает.
• Проверка актуальности: Примеры можно автоматически тестировать с помощью модуля doctest в Python, что гарантирует, что документация не устарела.
• Ускорение обучения: Новые разработчики или пользователи библиотеки быстрее разбираются в API, видя готовые фрагменты кода.

Где и как применяется?

Практика широко используется в экосистеме Python (например, в официальной документации стандартной библиотеки и популярных фреймворках вроде NumPy), а также в других языках с поддержкой подобных инструментов (например, RDoc в Ruby). Примеры включаются в секцию Examples docstring.

Пример кода

def calculate_discount(price: float, percent: float) -> float:
    """
    Рассчитывает итоговую цену после применения скидки.

    Args:
        price: Исходная цена.
        percent: Процент скидки (от 0 до 100).

    Returns:
        Цена после применения скидки.

    Examples:
        >>> calculate_discount(1000, 10)
        900.0
        >>> calculate_discount(500, 25)
        375.0
    """
    return price * (1 - percent / 100)

В этом примере секция Examples содержит два вызова функции. Эти строки можно скопировать, вставить в интерпретатор Python и сразу увидеть результат, а также проверить через python -m doctest module.py.

Вывод: Добавляйте примеры использования в docstring для создания самодостаточной, проверяемой и понятной документации, особенно в публичных API и библиотеках, где важно минимизировать порог входа для пользователей.