07 Июл 2023
2 мин
1307

Форматы docstring в Python

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

Содержание

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

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

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

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

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

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

3. Стиль NumPy/SciPy

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

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

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

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

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

Содержание

Добавить комментарий

Определи профессию по рисунку