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

📜 Где определены правила написания docstring в Python?

Базовые общепринятые правила написания docstring в Python определены в нескольких официальных документах. Главным источником является PEP 257 — Docstring Conventions, опубликованный Гвидо ван Россумом и Дэвидом Гудджером. Именно этот документ устанавливает соглашения о том, как следует писать и форматировать строки документации в Python-коде.

Помимо PEP 257, существуют смежные документы и стайл-гайды, которые расширяют или уточняют эти правила для конкретных случаев использования.

📄 Основные источники правил docstring

Документ Автор / Организация Что регулирует Статус
PEP 257 Гвидо ван Россум, Дэвид Гудджер Базовые соглашения по написанию docstring Активный стандарт
PEP 8 Гвидо ван Россум Общий стиль кода, включая краткие упоминания docstring Активный стандарт
Google Python Style Guide Google Расширенный формат docstring в стиле Google Корпоративный стандарт
NumPy Docstring Standard NumPy / SciPy Community Формат docstring для научного и технического кода Отраслевой стандарт
reStructuredText (Sphinx) Sphinx Project Формат разметки для автогенерации документации Широко используется
Epytext (Epydoc) Edward Loper Устаревший формат разметки docstring Устаревший
PEP 3107 / PEP 484 Python Core Team Аннотации типов, частично заменяющие описание типов в docstring Активный стандарт

📌 Ключевые правила PEP 257

PEP 257 является основополагающим документом для написания docstring в Python и описывает два вида строк документации: однострочные и многострочные.

Однострочные docstring

  • Используются для простых и очевидных объектов
  • Открывающие и закрывающие тройные кавычки """ располагаются на одной строке
  • Не должно быть пустых строк до или после однострочного docstring
  • Описание формулируется как команда, а не описание: «Вычислить сумму», а не «Вычисляет сумму»
  • Строка заканчивается точкой
def add(a, b):
    """Вычислить сумму двух чисел."""
    return a + b

Многострочные docstring

  • Состоят из краткого резюме на первой строке, затем пустой строки, затем подробного описания
  • Закрывающие """ располагаются на отдельной строке
  • Отступы соответствуют уровню вложенности объекта
  • После краткого резюме обязательна пустая строка перед детальным описанием
  • Для классов docstring описывает поведение, а не реализацию
  • Для модулей docstring располагается в самом начале файла, до импортов
def connect(host, port, timeout=30):
    """
    Установить соединение с удалённым сервером.

    Пытается подключиться к указанному хосту и порту.
    При неудаче по истечении timeout поднимает TimeoutError.

    Args:
        host (str): Адрес сервера.
        port (int): Номер порта.
        timeout (int): Время ожидания в секундах.

    Returns:
        socket: Объект соединения.

    Raises:
        TimeoutError: Если соединение не установлено за timeout секунд.
    """

🔍 Форматы оформления параметров

PEP 257 не диктует конкретный формат для описания аргументов и возвращаемых значений — это область, где различные стайл-гайды расходятся.

  • Google Style — использует секции Args:, Returns:, Raises: с отступами
  • NumPy Style — использует подчёркнутые заголовки секций, подходит для сложных API
  • reStructuredText (Sphinx) — использует директивы :param:, :type:, :returns:, :rtype:

⚙️ Правила для разных объектов

Объект Обязательность docstring Особенности
Публичный модуль Обязателен Перечисляет экспортируемые объекты, краткое описание назначения
Публичная функция / метод Обязателен Описывает поведение, аргументы, возвращаемое значение, исключения
Публичный класс Обязателен Описывает класс; docstring __init__ может быть включён в docstring класса
Приватный метод Необязателен, но рекомендован Достаточно однострочного описания
Пакет (__init__.py) Рекомендован Описывает пакет и перечисляет субмодули
Скрипт (исполняемый файл) Рекомендован Описывает использование, аргументы командной строки

🛠️ Инструменты проверки и генерации

Соответствие docstring стандартам можно автоматически проверить с помощью специализированных инструментов, что особенно важно в командной разработке.

  • pydocstyle — линтер для проверки соответствия PEP 257
  • flake8-docstrings — плагин для flake8, интегрирующий pydocstyle
  • Sphinx + autodoc — генератор документации из docstring
  • pdoc — лёгкий генератор документации
  • interrogate — проверяет покрытие кода docstring
  • darglint — проверяет соответствие docstring реальной сигнатуре функции

❓ FAQ по смежным темам

Чем docstring отличается от обычного комментария (#)?

Комментарий с символом # игнорируется интерпретатором и не сохраняется в байткоде. Docstring — это полноценный строковый литерал, который Python сохраняет в атрибуте __doc__ объекта и который доступен во время выполнения программы через help() и рефлексию.

Можно ли использовать одинарные кавычки вместо тройных в docstring?

Технически Python позволяет использовать любые кавычки, однако PEP 257 явно предписывает использовать тройные двойные кавычки """ для всех docstring — даже однострочных. Это обеспечивает единообразие и упрощает последующее расширение строки документации.

Нужно ли писать docstring для магических методов (dunder methods)?

Как правило, нет — магические методы вроде __init__, __str__, __repr__ достаточно хорошо известны по своей семантике. Исключение составляет __init__ в тех случаях, когда логика инициализации нетривиальна. Некоторые стайл-гайды (например, Google) рекомендуют переносить документацию параметров конструктора в docstring самого класса.

Как docstring связан с аннотациями типов (type hints)?

С появлением PEP 484 (type hints) и PEP 526 (аннотации переменных) необходимость указывать типы параметров прямо в docstring уменьшилась. Современная практика: типы указываются через аннотации в сигнатуре функции, а docstring фокусируется на семантическом описании поведения. Инструменты вроде Sphinx умеют читать оба источника одновременно.

Что такое «doctest» и как он связан с docstring?

Модуль doctest из стандартной библиотеки позволяет встраивать тесты прямо в docstring в виде интерактивных сессий Python (строки, начинающиеся с >>>). При запуске doctest извлекает эти примеры, выполняет их и сравнивает вывод с ожидаемым. Это удобно для простой документации с одновременной проверкой корректности примеров.

Какой формат docstring выбрать для нового проекта?

Если проект предполагает генерацию документации через Sphinx — используйте reStructuredText-формат. Если важна читаемость в исходном коде без генерации — Google Style или NumPy Style. Главное правило: выберите один формат и придерживайтесь его во всём проекте. Зафиксируйте выбор в файле CONTRIBUTING.md или конфигурации линтера.