Источник: Nuances of Programming
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками """<description>""" в начале модуля, класса, метода или функции, который описывает, что делает функция.
Только в случае, если это первый оператор в функции, он может быть распознан компилятором байт-кода Python и доступен как атрибуты объекта времени выполнения с помощью метода __doc__ или функции help().
Лучшие практики
- Все модули, классы, методы и функции, включая конструктор __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 , повторяющей параметры функции/метода.
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
- Легкого чтения программистами, которые читают и пишут исходный код Python.
Синтаксис Sphinx
В Sphinx используется такой же, как и в большинстве языков программирования синтаксис: keyword(reserved word). Наиболее важные ключевые слова:
- param и type: значение параметра и тип его переменной;
- return и rtype: возвращаемое значение и его тип;
- :raises: описывает любые ошибки, которые возникают в коде;
- .. seealso::: информация для дальнейшего чтения;
- .. notes::: добавление заметки;
- .. warning::: добавление предупреждения.
Хотя порядок этих ключевых слов не является фиксированным, (опять же) принято придерживаться вышеуказанного порядка на протяжении всего проекта. Записи seealso, notes и warning не являются обязательными.
Например, вы можете связывать параметры с помощью знака |, как показано тут:
Макет Sphynx
Общий макет этой строки документации показан ниже.
Вот и все.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
Читайте также:
Читайте нас в телеграмме и vk
Перевод статьи Louis de Bruijn: Start Writing Python Docstrings