Docstrings в Python: как писать понятную документацию

Что такое docstring

Docstring — это строка в начале модуля, класса или функции, которая объясняет, что делает код и как им пользоваться. Это не комментарий для разработчика; docstring — это интерфейс для пользователей кода: автоматическая документация, подсказки в IDE и примеры использования.

Краткое определение: Docstring — это встроенная документация в виде строки, доступная через doc и инструменты генерации документации.

Важно: docstring заключают в тройные кавычки (“””…”””) и помещают сразу после заголовка блока кода (def, class или в начале файла для модуля).

Почему docstrings важны

• Поддерживаемость: легче изменять код, когда его назначение описано.
• Коллаборация: командная документация единообразна и понятна всем разработчикам.
• Инструменты: IDE, Sphinx и другие генераторы читают docstrings.
• Тестирование: doctest позволяет встроить рабочие примеры прямо в документацию.

Основные правила хорошего docstring

• Начинайте с краткой сводки в одной строке.
• Пустая строка после сводки для многострочных docstring.
• Описывайте аргументы, возвращаемые значения и возможные исключения.
• Показывайте примеры использования и ожидаемый результат.
• Используйте аннотации типов (PEP 484) по возможности.
• Следуйте выбранному формату (Google, NumPy, reST) и документируйте стиль в CONTRIBUTING.md.

Простые и сложные docstrings — примеры

Однострочный docstring для простой функции:

def multiply(a, b):
    """Умножает два числа и возвращает результат."""
    return a * b

Многострочный docstring для класса и метода (Google-стиль):

class Car:
    """
    Класс, представляющий автомобиль.

    Attributes:
        mileage (float): Текущий пробег автомобиля в километрах.
    """

    def __init__(self, mileage: float):
        self.mileage = mileage

    def drive(self, miles: float) -> None:
        """
        Проезжает указанное количество километров.

        Args:
            miles (float): Число километров для прохождения.

        Returns:
            None
        """
        self.mileage += miles

Популярные форматы docstring и шаблоны

Ниже — четыре часто используемых формата. Выберите один и применяйте в проекте.

Google

def multiply(a: int, b: int) -> int:
    """
    Умножает два числа вместе.

    Args:
        a (int): Первое число.
        b (int): Второе число.

    Returns:
        int: Произведение a и b.

    Examples:
        >>> multiply(2, 3)
        6
    """
    return a * b

NumPy

def multiply(a: int, b: int) -> int:
    """
    Умножает два числа вместе.

    Parameters
    ----------
    a : int
        Первое число.
    b : int
        Второе число.

    Returns
    -------
    int
        Произведение a и b.
    """
    return a * b

reStructuredText (reST)

def multiply(a, b):
    """
    Умножает два числа вместе.

    :param a: Первое число.
    :type a: int
    :param b: Второе число.
    :type b: int
    :return: Произведение a и b.
    :rtype: int
    """
    return a * b

Epytext

def multiply(a, b):
    """
    Умножает два числа вместе.

    @param a: Первое число.
    @type a: int
    @param b: Второе число.
    @type b: int
    @return: Произведение a и b.
    @rtype: int
    """
    return a * b

Примечание: Google и NumPy форматы обычно легче читать и чаще используются в современных проектах.

Как включать тесты в docstrings с doctest

doctest ищет в docstring примеры в стиле интерактивной сессии Python и выполняет их. Это удобно для быстрых проверок и демонстраций.

Пример docstring с разделом Examples для doctest:

def multiply(a: int, b: int) -> int:
    """
    Умножает два числа вместе.

    Examples
    --------
    >>> multiply(2, 3)
    6
    >>> multiply(0, 10)
    0
    >>> multiply(-1, 5)
    -5
    """
    return a * b

Запускить doctest для файла можно командой:

python -m doctest -v your_module.py

Важно: doctest хорош для наглядных примеров и регрессионных тестов маленьких функций, но он не заменяет полноценные unit-тесты (pytest, unittest).

Генерация документации из docstrings

Sphinx — популярный генератор документации. Базовый подход:

1. Установите Sphinx и расширение napoleon, которое поддерживает Google и NumPy форматы:

pip install sphinx sphinx-rtd-theme sphinxcontrib-napoleon

2. Инициализируйте проект:

sphinx-quickstart

3. В conf.py включите napoleon:

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.napoleon',
]
html_theme = 'sphinx_rtd_theme'

4. Подключите модули через автодок:

.. automodule:: mypackage.mymodule
    :members:
    :undoc-members:

Sphinx создаст HTML-документацию из ваших docstrings. Это идеальный путь для публичных библиотек и внутренних API.

Лучшие практики и чеклист перед коммитом

• Напишите краткую сводку в первой строке.
• Убедитесь, что аргументы и возвращаемые значения документированы.
• Приведите пример использования (один краткий пример). Если функция публичная — добавьте примеры для краевых случаев.
• Поддерживайте формат проекта (Google/NumPy/reST).
• Запустите doctest и базовые unit-тесты.
• Добавьте ссылку в CHANGELOG или документацию, если поведение изменилось.

Короткий чеклист для ревьюера:

• Соответствует ли docstring выбранному формату?
• Покрыты ли все параметры и исключения?
• Есть ли пример использования для ключевых функций?
• Не раскрывает ли docstring детали реализации, которые должны быть скрыты?

Короткий чеклист для автора:

• Есть ли однострочная сводка?
• Есть ли пустая строка после неё в многострочных docstrings?
• Прописаны ли типы (если релевантно)?

Мини‑методология: как писать хорошую документацию за 10–20 минут

1. Опишите цель функции в одной строке.
2. Добавьте аргументы и типы (или ссылку на typing). Если параметров нет — пропустите раздел Args.
3. Опишите возвращаемое значение и тип.
4. Укажите побочные эффекты (изменение состояния, I/O, запись в БД).
5. Добавьте 1–2 примера: обычный и краевой случай.
6. Запустите doctest и unit-тесты, поправьте ошибки.
7. Коммит и ссылка в описании задачи.

Когда docstrings не помогут: ограничения и контрпримеры

• Документация не заменит плохую структуру кода. Если функция слишком длинная — лучше вынести части в отдельные функции.
• Docstrings не могут полностью объяснить архитектурные решения и бизнес-логику — нужен внешний документ (ARCHITECTURE.md).
• Слишком подробные docstrings с внутренними деталями усложняют чтение: держите баланс.

Альтернативы и дополняющие подходы

• README с примерами и общей картиной модуля.
• ARCHITECTURE.md для описания высокоуровневых решений.
• CHANGELOG для описания изменений поведения API.
• Inline-комментарии для тонких реализаций — только если они поясняют мотивацию.

Роль‑ориентированные рекомендации

Разработчик:

• Пиши кратко, делай примеры, поддерживай стиль.

Ревьюер:

• Проверь полноту аргументов и корректность примеров.

Техлид / архитектор:

• Определи формат и включи в CONTRIBUTING.md.

Документатор:

• Настрой Sphinx/ReadTheDocs и CI, чтобы сборка падала при ошибках в документации.

Cheat sheet — быстрая шпаргалка

• Однострочный docstring: для приватных или очень простых функций.
• Многострочный: для публичных API, классов и модулей.
• Формат: Google или NumPy для удобочитаемости.
• Примеры: обязательно для публичных функций.
• Тесты: doctest + unit-тесты.

Примеры шаблонов для копирования

Функция (Google):

def func(arg1: str, arg2: int) -> bool:
    """
    Краткое описание.

    Args:
        arg1 (str): Описание arg1.
        arg2 (int): Описание arg2.

    Returns:
        bool: Описание возвращаемого значения.

    Raises:
        ValueError: Если arg2 отрицательный.
    """
    if arg2 < 0:
        raise ValueError("arg2 must be non-negative")
    return True

Класс (NumPy):

class DataProcessor:
    """
    Обрабатывает данные для загрузки.

    Parameters
    ----------
    config : dict
        Конфигурация обработки.

    Attributes
    ----------
    config : dict
        Текущая конфигурация.
    """
    def __init__(self, config: dict):
        self.config = config

Критерии приёмки

• Docstring присутствует для публичной функции/класса/модуля.
• Есть краткая первая строка и описание параметров.
• Примеры демонстрируют нормальное и краевое поведение.
• doctest и unit-тесты проходят в CI.

Миграция и совместимость

Если вы менять формат docstring в существующем проекте:

1. Выберите новый формат и задокументируйте его в CONTRIBUTING.md.
2. Автоматизируйте проверку линтером (pydocstyle поддерживает разные правила).
3. Мигрируйте по модулям: новые изменения — в новом формате, старые — постепенно.
4. Настройте CI, чтобы новый стиль соблюдался.

Security и приватность

Не включайте в docstrings секреты, ключи доступа или конфиденциальные данные. Docstrings часто попадают в публичную документацию и в логи.

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

Decision flowchart — выбрать формат docstring

flowchart TD
    A[Нужна простая документация?] -->|Да| B[Однострочный docstring]
    A -->|Нет| C[Публичный API или библиотека]
    C --> D{Нужна читабельность для научных пользователей?}
    D -->|Да| E[NumPy формат]
    D -->|Нет| F[Google формат]
    E --> G[Настроить sphinxcontrib-napoleon]
    F --> G
    B --> H[Минимум: краткая строка и пример]
    G --> I[Автоматизировать CI и линтинг]

Короткое объявление для канала команды (100–200 слов)

Docstrings — это встроенная документация к функциям, классам и модулям Python. Согласованный стиль docstring ускоряет разработку и облегчает генерацию пользовательской документации с помощью Sphinx. Рекомендуется использовать Google или NumPy формат для публичных API, включать примеры и базовые doctest, а также автоматизировать проверку через CI. Пропишите стиль в CONTRIBUTING.md и начните миграцию модулей по очереди.

Короткий итог

Docstrings делают код понятнее и безопаснее при совместной работе. Выберите формат, автоматизируйте проверку и не храните в документации конфиденциальную информацию. Начните с простых однострочных описаний и расширяйте их для публичных модулей.