Хороший код содержит комментарии, помогающие понять его, и строки документации могут сыграть в этом важную роль.

Без надлежащей документации может быть сложно понять, поддерживать и отлаживать код. В Python вы можете использовать строки документации, чтобы предоставить краткие описания и примеры того, как работает код.

Что такое строки документации?

Строки документации — это строки, которые вы можете добавить в свой код Python, чтобы объяснить, что он делает и как его использовать. Часть кода может быть Функция Python, модуль или класс.

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

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

instagram viewer

Как писать строки документации

Обычно вы включаете строки документации в начале блока кода, который хотите задокументировать. Вы должны заключить их в тройные кавычки (). Вы можете писать однострочные или многострочные строки документации.

Однострочные строки документации подходят для простого кода, не требующего большого количества документации.

Ниже приведен пример функции с именем умножить. Строка документации объясняет, что функция умножения принимает два числа, умножает их и возвращает результат.

дефумножать(а, б):
Умножает два числа и возвращает результат
возвращаться а * б

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

Рассмотрим следующий класс Car:

сортМашина:

 А сортпредставляющийамашинаобъект.
 Атрибуты:
 mileage (float): Текущий пробег автомобиля.


 Методы:
 вождение (мили): водит машину для указанное количество миль.


деф__в этом__(самостоятельно, пробег):
 self.mileage = пробег


дефводить машину(самостоятельно, мили):

 водит машину для указанное количество миль.


 Аргументы:
 мили (с плавающей запятой): количество миль, которые нужно проехать.
 Возвращает:
Никто

 self.mileage += миль

Строка документации для приведенного выше класса описывает, что представляет собой класс, его атрибуты и методы. Между тем, строки документации для метода drive предоставляют информацию о том, что делает метод, какие аргументы он ожидает и что он возвращает.

Это позволяет любому, кто работает с этим классом, понять, как его использовать. Другие преимущества использования строк документации включают в себя:

  • Сопровождаемость кода. Предоставляя четкое описание того, как работает код, строки документации помогают разработчикам модифицировать и обновлять код, не допуская ошибок.
  • Упрощение совместной работы. Когда несколько разработчиков работают над одной и той же кодовой базой, например, с Инструмент живого обмена Visual StudioСтроки документации позволяют разработчикам последовательно документировать код, чтобы каждый член команды мог его понять.
  • Улучшенная читабельность кода: строки документации предоставляют высокоуровневую сводку того, что делает код, что позволяет любой, кто читает код, чтобы быстро понять его назначение, не просматривая весь код блокировать.

Форматы строк документации

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

Базовый формат строки документации состоит из следующих разделов:

  • Сводная строка: однострочное резюме того, что делает код.
  • Аргументы: информация об аргументах, ожидаемых функцией, включая их типы данных.
  • Возвращаемое значение: Информация о возвращаемом значении функции, включая ее тип данных.
  • Raises (необязательно): информация о любых исключениях, которые может вызвать функция.

Это всего лишь базовый формат, так как есть и другие форматы, которые вы можете выбрать для своих строк документации. Наиболее популярными из них являются Epytext, reStructuredText (также известный как reST), NumPy и строки документации Google. Каждый из этих форматов имеет собственный синтаксис, как показано в следующих примерах:

эпитекст

Строка документации в формате Epytext:

дефумножать(а, б):

 Умножьте два числа вместе.
 @param a: первое число для умножения.
 @тип а: целое
 @param b: второе число для умножения.
 @тип b: целое число
 @return: Произведение двух чисел.
 @rтип: целое

возвращаться а * б

реструктурированный текст (reST)

Строка документации в формате reST:

дефумножать(а, б):

 Умножьте два числа вместе.
 :param a: Первое число для умножения.
: тип а: интервал
 :param b: Второе число для умножения.
: тип b: интервал
 :возвращаться: Произведение двух чисел.
 :rtype: интервал

возвращаться а * б

NumPy

Строка документации в формате NumPy:

дефумножать(а, б):

 Умножьте два числа вместе.
 Параметры

 а: инт
 Первое число для умножения.
 б: между
 Второе число для умножения.
 Возвращает

 инт
 Произведение двух чисел.

возвращаться а * б

Google

Строка документации в формате Google:

дефумножать(а, б):

 Умножьте два числа вместе.
 Аргументы:
 a (int): первое число для умножения.
 b (int): Второе число для умножения.
 Возвращает:
 int: Произведение двух чисел.

возвращаться а * б

Хотя все четыре формата строк документации содержат полезную документацию для функции умножения, форматы NumPy и Google легче читать, чем форматы Epytext и reST.

Как включить тесты в строки документации

Вы можете включать примеры тестирования в свои строки документации с помощью модуля doctest. Модуль doctest ищет в строке документации текст, который выглядит как интерактивные сеансы Python, а затем выполняет их, чтобы убедиться, что они работают должным образом.

Чтобы использовать тесты документации, включите примеры входных данных и ожидаемых выходных данных в строку документации. Ниже приведен пример того, как вы это сделаете:

дефумножать(а, б):

 Умножьте два числа вместе.
 Параметры

 а: инт
 Первое число для умножения.
 б: между
 Второе число для умножения.


 Возвращает

 инт
 Произведение двух чисел.
 Примеры

 >>> умножить(2, 3)
6
 >>> умножить(0, 10)
0
 >>> умножить(-1, 5)
-5

возвращаться а * б

Примеры Раздел содержит три вызова функций с разными аргументами и указывает ожидаемый результат для каждого из них. Когда вы запускаете модуль doctest, как показано ниже, он выполняет примеры и сравнивает фактический результат с ожидаемым.

python -m doctest умножить.py

Если есть какие-либо различия, модуль doctest сообщает о них как об ошибках. Использование doctests с подобными строками документации помогает убедиться, что код работает должным образом. Обратите внимание, что doctests не заменяет более полные модульные тесты и интеграционные тесты для вашего кода Python.

Как создать документацию из строк документации

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

Одним из самых популярных генераторов документации, который вы можете использовать, является Sphinx. По умолчанию он поддерживает формат строки документации reST, но вы можете настроить его для работы с форматом Google или NumPy.