Практическое руководство по докстрингам в Python

Что такое докстринги?

Докстринги — это строковые литералы, расположенные сразу после определения функции, метода, класса или модуля. Они служат для документирования интерфейса кода: что делает объект, какие принимает аргументы, что возвращает и какие исключения может выбросить.

Коротко: докстринг — это самоописание куска кода, доступное в рантайме через атрибут doc.

Важно понимать разницу между докстрингами и комментариями:

• Комментарии ( # ) предназначены для разработчиков и поясняют реализацию.
• Докстринги предназначены для пользователей API и инструментов генерации документации.

Почему писать докстринги важно

• Поддерживаемость: понятные докстринги ускоряют внесение изменений без регресcий.
• Коллаборация: единый стиль докстрингов помогает команде быстро понять API.
• Автогенерация документации: инструменты (Sphinx, pydoc, mkdocs) используют докстринги как источник правды.
• Быстрая справка в интерактивной сессии: help(my_func) выводит докстринг.

Как правильно писать докстринг

Общие рекомендации:

• Используйте тройные кавычки (“””) даже для односложных описаний — это ожидаемый стандарт.
• Первая строка должна быть короткой сводкой (одна-две фразы).
• После сводки при необходимости добавьте пустую строку и развернутое описание, примеры или ограничения.
• Пишите в повелительном наклонении: “Выполняет X”, “Возвращает Y”.
• Указывайте типы аргументов и возвращаемых значений, особенно если проект не использует явные type hints.
• Добавляйте примеры использования и doctest для простых проверок.

Примеры из практики (читайте кодовые блоки, они сохранены в исходном виде):

def multiply(a, b):  
    """Multiplies two numbers and returns the result"""  
    return a * b  

Для более сложных объектов используйте многострочные докстринги с разделами Attributes/Args/Returns и т. п.:

class Car:  
    """  
    A class representing a car object.  
  
    Attributes:  
        mileage (float): The current mileage of the car.  
  
    Methods:  
        drive(miles): Drives the car for the specified number of miles.  
    """  
  
    def __init__(self, mileage):  
        self.mileage = mileage  
  
    def drive(self, miles):  
        """  
        Drives the car for the specified number of miles.  
  
        Args:  
            miles (float): The number of miles to drive.  
  
        Returns:  
            None  
        """  
        self.mileage += miles  

Основные разделы хорошего докстринга

Часто используемые секции, которые следует включать по мере необходимости:

• Сводка: одна строка, цель функции/класса.
• Аргументы / Parameters / Args: имена, типы и краткое описание.
• Возвращаемое значение / Returns: тип и описание.
• Исключения / Raises: какие исключения могут быть подняты и при каких условиях.
• Примеры / Examples: типичные вызовы и ожидаемый результат.
• Примечания / Notes: ограничения, побочные эффекты, сложная логика.

Популярные форматы докстрингов

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

Epytext

def multiply(a, b):  
    """  
    Multiply two numbers together.  
  
    @param a: The first number to multiply.  
    @type a: int  
    @param b: The second number to multiply.  
    @type b: int  
    @return: The product of the two numbers.  
    @rtype: int  
    """  
    return a * b  

reStructuredText (reST)

def multiply(a, b):  
    """  
    Multiply two numbers together.  
  
    :param a: The first number to multiply.  
    :type a: int  
    :param b: The second number to multiply.  
    :type b: int  
    :return: The product of the two numbers.  
    :rtype: int  
    """  
    return a * b  

reST — стандарт для Sphinx по умолчанию и удобно интегрируется с автогенерацией.

NumPy

def multiply(a, b):  
    """  
    Multiply two numbers together.  
  
    Parameters  
    ----------  
    a : int  
        The first number to multiply.  
    b : int  
        The second number to multiply.  
  
    Returns  
    -------  
    int  
        The product of the two numbers.  
    """  
    return a * b  

NumPy-стиль часто встречается в научных и численных проектах.

Google

def multiply(a, b):  
    """  
    Multiply two numbers together.  
  
    Args:  
        a (int): The first number to multiply.  
        b (int): The second number to multiply.  
  
    Returns:  
        int: The product of the two numbers.  
    """  
    return a * b  

Google-стиль читается легко и часто используется в корпоративных кодовых базах.

Совет: выберите стиль, добавьте линтер/formatter (например, pydocstyle, ruff с плагинами) и включите проверку докстрингов в CI.

Как включать тесты прямо в докстринги (doctest)

Doctest позволяет вставлять пример интерактивной сессии в докстринг, который затем проверяется модулем doctest.

Пример (включён в исходный код):

def multiply(a, b):  
    """  
    Multiply two numbers together.  
  
    Parameters  
    ----------  
    a : int  
        The first number to multiply.  
    b : int  
        The second number to multiply.  
  
    Returns  
    -------  
    int  
        The product of the two numbers.  
  
    Examples  
    --------  
    >>> multiply(2, 3)  
    6  
    >>> multiply(0, 10)  
    0  
    >>> multiply(-1, 5)  
    -5  
    """  
    return a * b  

Чтобы прогнать doctest из командной строки:

python -m doctest multiply.py  

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

Как генерировать документацию из докстрингов

Инструменты и подходы:

• Sphinx: классический инструмент для генерации HTML/PDF документации. Поддерживает reST natively; есть плагины для NumPy/Google стилей (sphinx.ext.napoleon).
• pydoc / pydoc3: быстро показывает документацию в консоли.
• mkdocs + mkdocstrings: современная генерация документации с поддержкой Markdown и докстрингов.
• autodoc и napoleon (Sphinx): позволяют подтягивать докстринги из кода и форматировать их в итоговой документации.

Рекомендация: для среднего и крупного проекта используйте Sphinx + napoleon, чтобы сохранить совместимость с реST и Google/NumPy стилями.

Когда докстринги не решают проблему (когда они не помогают)

• Когда код сложен из-за плохой архитектуры: подробный докстринг не исправит плохой дизайн.
• Когда поведение меняется динамически (метапрограммирование) — докстринг нужно поддерживать, и он быстро устаревает.
• Когда требуются доказательства корректности — докстринги не заменяют тесты и формальную верификацию.

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

• Type hints: явные аннотации типов делают интерфейс понятнее и дают подсказки IDE.
• Внешняя документация: отдельные руководства, архитектурные диаграммы, спецификации API (OpenAPI для HTTP-сервисов).
• Inline comments: поясняют реализацию там, где логика нетривиальна.

Используйте комбинацию: докстринги для интерфейса, type hints для статической проверки и внешнюю документацию для архитектурных решений.

Практическая методология: как написать докстринг за 5 шагов

1. Напишите короткую сводку в одной строке: что делает функция/класс.
2. Добавьте описание аргументов и типов.
3. Опишите возвращаемое значение и возможные исключения.
4. Приведите 1–3 примера вызовов; добавьте doctest для простых функций.
5. Проверяйте докстринг через linters/CI и обновляйте при изменениях API.

Ролевая проверка: чеклисты

Автор:

• Есть ли однастрочная сводка?
• Указаны ли все аргументы и типы?
• Есть ли пример использования?

Рецензент:

• Соответствует ли стиль принятому в проекте?
• Являются ли типы и возвращаемые значения корректными?
• Обновлён ли doctest/тесты при изменении поведения?

Поддерживающий (maintainer):

• Поддерживает ли CI проверки докстрингов?
• Документация генерируется без ошибок (Sphinx/mkdocs)?

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

Чтобы принять PR с новой функцией, докстринг должен:

• Иметь краткую сводку и раздел с аргументами.
• Содержать пример использования (минимум один) или ссылку на тесты.
• Проходить линтеры докстрингов в CI.

Быстрые эвристики и ментальные модели

• “Докстринг для пользователя API”: опишите контракт, а не реализацию.
• “Пиши для новичка”: представьте, что код прочитает человек, не знакомый с проектом.
• “Краткость, затем детали”: первая строка — цель; далее — детали.

Факт-бокс: ключевые числа и понятия

• 4 популярных формата: Epytext, reST, NumPy, Google.
• 4 типичных секции: сводка, аргументы, возвращаемое значение, исключения.
• Тройные кавычки (“””) — стандартный синтаксис для докстрингов.

Глоссарий (одна строка)

• Докстринг: встроенная строка документации в Python, доступная через doc.
• doctest: модуль для проверки примеров в докстрингах.
• Sphinx: генератор документации, часто использующий формат reST.

Короткое резюме

Докстринги — недорогой и эффективный способ улучшить качество кода и документации. Выберите стиль, автоматизируйте проверку в CI и комбинируйте докстринги с type hints и тестами.

Важно: документируйте контракт интерфейса, а не детали реализации. Поддерживайте докстринги синхронизированными с кодом и тестами.