Форматы docstring в Python

В мире программирования на Python есть несколько распространенных стилей написания документации или «docstring». Это специальные комментарии, которые описывают, что делает функция или класс и как их использовать.

Пример простого docstring выглядит так:

def add(a, b):
    """
    Возвращает сумму двух чисел
    """
    return a + b

Здесь строка, заключенная в тройные кавычки, служит docstring для функции add.

Теперь рассмотрим наиболее популярные стили написания docstring.

Освойте Python на курсе от Skypro. Вас ждут 400 часов обучения и практики (достаточно десяти часов в неделю), подготовка проектов для портфолио, индивидуальная проверка домашних заданий и помощь опытных наставников. Получится, даже если у вас нет опыта в IT.

1. Стиль Google

В этом стиле сначала дается общее описание, затем перечисляются аргументы и возвращаемое значение. Пример:

def add(a, b):
    """
    Суммирует два числа.

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

    Returns:
        int: Сумма двух чисел
    """
    return a + b

2. Стиль reStructuredText

Этот стиль был предложен в документации Python. Он включает в себя использование специальных тэгов.

def add(a, b):
    """
    Суммирует два числа.

    :param a: Первое число
    :param b: Второе число
    :return: Сумма двух чисел
    """
    return a + b

На курсе Skypro «Python-разработчик» освоите основные инструменты программирования, получите опыт на реальных проектах и сможете стартовать в профессии уверенным новичком. Преподаватели — практикующие программисты с большим опытом, а в центре карьеры помогут составить цепляющее резюме и подготовиться к собеседованию.

3. Стиль NumPy/SciPy

Этот стиль часто используется в научных библиотеках. Он похож на стиль Google, но имеет несколько дополнительных секций.

def add(a, b):
    """
    Суммирует два числа.

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

    Returns
    -------
    int
        Сумма двух чисел
    """
    return a + b

Эти три стиля являются самыми популярными, но выбор стиля зависит от предпочтений разработчика и команды. Главное — чтобы документация была понятной и помогала другим разработчикам понять, как работает код.