Форматы docstring: Google Style, NumPy, reStructuredText

В прошлом уроке мы узнали, что такое docstring. Теперь разберёмся, как его правильно оформлять. В Python существует три главных формата — каждый со своими правилами записи. Разберём все три на одном и том же примере и решим, какой выбрать.

🤔 Зачем нужны форматы — разве тройных кавычек не достаточно?

Python требует только одного: docstring должен начинаться с тройных кавычек и стоять сразу после объявления функции или класса. Никаких правил о том, как именно писать содержимое внутри — в стандарте нет.

На практике это привело к тому, что каждый писал docstring по-своему. Параметры кто-то описывал через тире, кто-то в скобках, кто-то вообще не описывал. Чтение таких docstring'ов превращалось в квест.

Поэтому сообщество выработало соглашения — единые правила оформления. Главных три:

🧪 Наша подопытная функция

Чтобы честно сравнить все три формата, мы возьмём одну и ту же функцию и запишем её docstring тремя способами. Вот наша функция:

def calculate_bmi(weight, height):
    if height <= 0:
        raise ValueError("Рост должен быть больше нуля")
    bmi = weight / (height ** 2)
    return round(bmi, 2)

Google Style был разработан и популяризован компанией Google для внутренних Python-проектов. Сегодня это самый распространённый формат в современных open-source библиотеках и продуктовых командах.

Главная идея: секции обозначаются заголовком с двоеточием (Args:, Returns:, Raises:), а содержимое каждой секции пишется с отступом в 4 пробела.

def calculate_bmi(weight, height):
    """
    Вычисляет индекс массы тела (ИМТ) человека.

    Индекс массы тела — это число, которое показывает,
    соответствует ли вес человека его росту. Вычисляется
    по формуле: weight / height ** 2.

    Args:
        weight (float): Вес человека в килограммах.
            Должен быть положительным числом.
        height (float): Рост человека в метрах.
            Должен быть больше нуля.

    Returns:
        float: ИМТ, округлённый до 2 знаков после запятой.

    Raises:
        ValueError: Если height равен нулю или отрицателен.

    Example:
        >>> calculate_bmi(70, 1.75)
        22.86
        >>> calculate_bmi(90, 1.80)
        27.78
    """
    if height <= 0:
        raise ValueError("Рост должен быть больше нуля")
    bmi = weight / (height ** 2)
    return round(bmi, 2)

Разберём структуру по частям:

NumPy Style разработан командой NumPy — одной из важнейших научных библиотек Python. Его используют NumPy, SciPy, pandas, scikit-learn и другие инструменты для науки о данных.

Главная идея: каждая секция обозначается заголовком, а под заголовком проводится горизонтальная черта из дефисов такой же длины, как заголовок. Параметры описываются более развёрнуто — тип пишется не в скобках, а на следующей строке.

def calculate_bmi(weight, height):
    """
    Вычисляет индекс массы тела (ИМТ) человека.

    Индекс массы тела — это число, которое показывает,
    соответствует ли вес человека его росту. Вычисляется
    по формуле: weight / height ** 2.

    Parameters
    ----------
    weight : float
        Вес человека в килограммах.
        Должен быть положительным числом.
    height : float
        Рост человека в метрах.
        Должен быть больше нуля.

    Returns
    -------
    float
        ИМТ, округлённый до 2 знаков после запятой.

    Raises
    ------
    ValueError
        Если height равен нулю или отрицателен.

    Examples
    --------
    >>> calculate_bmi(70, 1.75)
    22.86
    >>> calculate_bmi(90, 1.80)
    27.78
    """
    if height <= 0:
        raise ValueError("Рост должен быть больше нуля")
    bmi = weight / (height ** 2)
    return round(bmi, 2)

Обратите внимание на ключевые отличия от Google Style:

reStructuredText (сокращённо reST) — это язык разметки, созданный специально для документации Python. Именно его использует Sphinx — самая популярная система генерации документации. Официальный PEP 287 рекомендует reST как стандарт.

Главная идея: каждый элемент описывается отдельной директивой-тегом с двоеточиями: :param имя:, :type имя:, :return:, :rtype:, :raises ТипОшибки:. Никаких секций — каждый параметр описывается на своей строке.

def calculate_bmi(weight, height):
    """
    Вычисляет индекс массы тела (ИМТ) человека.

    Индекс массы тела — это число, которое показывает,
    соответствует ли вес человека его росту. Вычисляется
    по формуле: weight / height ** 2.

    :param weight: Вес человека в килограммах.
    :type weight: float
    :param height: Рост человека в метрах. Должен быть больше нуля.
    :type height: float
    :return: ИМТ, округлённый до 2 знаков после запятой.
    :rtype: float
    :raises ValueError: Если height равен нулю или отрицателен.

    Пример использования::

        >>> calculate_bmi(70, 1.75)
        22.86
    """
    if height <= 0:
        raise ValueError("Рост должен быть больше нуля")
    bmi = weight / (height ** 2)
    return round(bmi, 2)

Запомните эти теги — именно их распознаёт Sphinx и IDE:

⚖️ Сравнение форматов — таблица

Теперь посмотрим на три формата рядом, чтобы понять разницу наглядно.

📐 Структура хорошего docstring — универсальный шаблон

Независимо от выбранного формата, структура хорошего docstring всегда следует одному и тому же порядку. Это порядок закреплён в PEP 257 и является общепринятой практикой:

🏆 Какой формат выбрать? Наша рекомендация

Вопрос не в том, какой формат «правильный» — все три правильные. Вопрос в том, какой подходит вашей ситуации.

📌 Быстрый справочник — ключевые секции

Шпаргалка: одни и те же элементы в трёх форматах.

# Параметры

# Google Style:
# Args:
#     name (type): описание.

# NumPy Style:
# Parameters
# ----------
# name : type
#     описание.

# reStructuredText:
# :param name: описание.
# :type name: type


# Возвращаемое значение

# Google Style:
# Returns:
#     type: описание.

# NumPy Style:
# Returns
# -------
# type
#     описание.

# reStructuredText:
# :return: описание.
# :rtype: type


# Исключения

# Google Style:
# Raises:
#     ValueError: когда возникает.

# NumPy Style:
# Raises
# ------
# ValueError
#     когда возникает.

# reStructuredText:
# :raises ValueError: когда возникает.

✅ Итоги урока

• Три главных формата: Google Style, NumPy Style и reStructuredText — каждый со своим синтаксисом секций.
• Google Style использует заголовки с двоеточием (Args:, Returns:, Raises:) и отступы — лаконичный и читаемый.
• NumPy Style использует заголовок и строку дефисов под ним, тип и описание параметра на отдельных строках — подробный и структурированный.
• reStructuredText использует теги-директивы (:param:, :type:, :return:, :rtype:, :raises:) — официальный формат Sphinx.
• Структура docstring: краткое описание → пустая строка → детали → Args → Returns → Raises → Examples.
• Рекомендация: для большинства проектов используйте Google Style — он популярнее всего и легче читается.
• Железное правило: один формат на весь проект. Смешивать форматы — недопустимо.

👉 В следующем уроке мы познакомимся с type hints — аннотациями типов в Python. Вы узнаете, как совмещать аннотации типов и docstring, чтобы ваш код был максимально понятным и помогал IDE находить ошибки ещё до запуска программы.