Учимся писать строки документации в Python

Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.

Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.

Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.

Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.

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

Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками """<description>""" в начале модуля, класса, метода или функции, который описывает, что делает функция.

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

def show_docstring(): 
    """Print function description to user"""
    print("Using __doc__ method:")
    print(show_docstring.__doc__)

    print("Using help() function:")
    help(show_docstring)

$ show_docstring();
"Using __doc__ method:"
"Print function description to user"
"Using help() function:"
"Print function description to user"

Лучшие практики

Все модули, классы, методы и функции, включая конструктор __init__в пакетах, должны иметь строки документации.

Описания пишутся с заглавной буквы и включают пунктуацию в конце предложения.

Всегда окружайте строки документации двойными кавычками по три раза, как показано тут: """Triple double quotes.""".

В конце докстринга пустая строка не ставится.

Однострочные докстринги

def power(a, b): 
    """Returns arg1 raised to power arg2."""
    return a**b

Однострочный докстринг прописывает функцию или действие метода как команду, а не как описание функции: """Do this, return that""".

Однострочный докстринг не является “подписью” function(a, b) -> list , повторяющей параметры функции/метода.

Многострочные докстринги

def suggest_places(auth_key, city):
  """Returns longitude and latitude of first suggested location in the Netherlands from Postcode API.
  
  :param auth_key: authorization key for Postcode API
  :type auth_key: str
  :param city: textual input for city names to match in Postcode API
  :type city: str
  
  :rtype: (str, str), str, str
  :return: (longitude, latitude), Postcode API status code, Postcode API error message

Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.

Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.

Стиль Sphinx

Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.

Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:

Обработки специальным программным обеспечением, таким как Docutils.

Легкого чтения программистами, которые читают и пишут исходный код Python.

def multiply(a, b, c=0):
    """Return sum of multiplication of all arguments.
 
    :param a: arg1
    :type a: int
    :param b: arg2
    :type b: int
    :param c: arg3, defaults to 0
    :type c: int, optional

    :raises ValueError: if arg1 is equal to arg2
    
    :rtype: int
    :return: multiplication of all arguments 
    """
    if a == b:
        raise ValueError('arg1 must not be equal to arg2')

    return a*b*c

Синтаксис Sphinx

В Sphinx используется такой же, как и в большинстве языков программирования синтаксис: keyword(reserved word). Наиболее важные ключевые слова:

param и type: значение параметра и тип его переменной;
return и rtype: возвращаемое значение и его тип;
:raises: описывает любые ошибки, которые возникают в коде;
.. seealso::: информация для дальнейшего чтения;
.. notes::: добавление заметки;
.. warning::: добавление предупреждения.

Хотя порядок этих ключевых слов не является фиксированным, (опять же) принято придерживаться вышеуказанного порядка на протяжении всего проекта. Записи seealso, notes и warning не являются обязательными.

Например, вы можете связывать параметры с помощью знака |, как показано тут:

:param x: An integer, defaults to None
:type x: int:param y: An integer or string

:param y: An integer or string
:type y: int|string

Макет Sphynx

Общий макет этой строки документации показан ниже.

"""< Summary. >

:param <variable_name>: <variable_description>, defaults to <default_value>
:type <variable_name>: <variable_type>(, optional)
<other parameters and types>

:raises <error_type>: <error_description>
<other exceptions>

:rtype: <return_type>
:return: <return_description>
"""

Вот и все.

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

Перевод статьи Louis de Bruijn: Start Writing Python Docstrings

Поделиться статьей:

Вернуться к статьям