как задокументировать код в python

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

May 28, 2020 · 4 min read

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

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

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

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

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

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

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

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

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

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

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

Стиль Sphinx

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

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

Синтаксис Sphinx

Макет Sphynx

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

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

Источник

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

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

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

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

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

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

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

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

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

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

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

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

Стиль Sphinx

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

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

Синтаксис Sphinx

Макет Sphynx

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

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

Источник

Документирование кода в Python

Д окументирование кода – неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.

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

Docstring

Документация для классов

Документация класса создается для самого класса, а также для его методов.

class Speak(): «»»Это docstring класса Speak.»»» def say_something(self): «»»Это docstring метода»»» print(«something»)

После строки документации нужно оставлять пустую строку.

Документация для класса может содержать следующую информацию:

Для методов класса документация может содержать:

Ниже – пример с более подробной документацией класса:

Документация для пакетов

Документация пакета размещается в файле __init__.py в верхней части файла (начиная с 1-й строки). В ней может быть указано:

Документация для модулей

Документация модулей аналогична документации классов. Вместо класса и методов в данном случае документируется модуль со всеми его функциями. Размещается в верхней части файла (начиная с 1-й строки).

Форматы Docstring

Строки документации могут иметь различное форматирование. В примере выше мы использовали стиль NumPy. Существуют и другие форматы:

Вывод документации на экран – help() и __doc__

Строки документации доступны:

Выведем документацию с помощью функции help()

Также можно выводить документацию отдельного объекта:

>>> import my_module >>> my_module.__doc__ >>> my_module.my_function.__doc__ >>> my_module.MyClass.__doc__ >>> my_module.MyClass.my_method.__doc__

Pydoc

Для более удобной работы с документацией, в Python существует встроенная библиотека pydoc.

Pydoc автоматически генерирует документацию из Python модулей. Информацию по доступным командам модуля pydoc можно получить набрав в терминале:

Разберем подробнее, что умеет pydoc.

Вывод текста документации

pydoc – покажет текст документации указанного модуля, пакета, функции, класса и т.д. Если содержит «\», Python будет искать документацию по указанному пути.

Для примера, посмотрим документацию встроенного модуля math:

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

Поиск по документации

Допустим, нам нужно распаковать gzip файл. Поищем слово » gzip «:

По описанию, данный модуль решит нашу задачу.

HTTP сервер с документацией

Для удобства просмотра документации, pydoc позволяет одной командой создать HTTP-сервер:

Теперь можно перейти в браузер и зайти на http://localhost:331/

Для остановки сервера введите » q » и нажмите » Enter «:

server> q Server stopped

Запись документации в файл

Автодокументирование кода

Pyment работает следующим образом:

Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.

pip install pyment

Для большинства IDE также существуют плагины, помогающие документировать код:

В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно:

Источник

Docstrings: документирование кода в Python

Хочешь знать больше о Python?

Подпишись на наш канал о Python в Telegram!

В статье, опубликованной на сайте pythonist.ru, рассмотрены строки документации в Python. Давайте разберемся, как и зачем их использовать.

Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.

Пример 1: Строки документации.

Здесь строковый литерал:

Принимает число n, возвращает квадрат числа n

Комментарии vs строки документации Python

Комментарии Python

Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.

В Python мы используем символ # для написания однострочного комментария. Например,

Комментарии Python с использованием строк

Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,

Примечание. Мы используем тройные кавычки для многострочных строк.

Строки документации Python

Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.

Атрибут __doc__

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

Пример 2: Вывод на экран строки документации.

Принимает число n, возвращает квадрат числа n

Теперь давайте посмотрим на строки документации для встроенной функции print() :

Пример 3: строки документации для встроенной функции print().

Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.

Однострочные строки документации в Python

Однострочные строки документации должны помещаться на одной строке.

Стандартные соглашения для написания однострочных строк документации:

Давайте посмотрим на пример ниже.

Пример 4: Однострочная строка документации для функции.

Многострочные строки документации в Python

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

Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.

Некоторые из них перечислены ниже:

1. Строки документации для модулей Python

Строки документации пишутся в начале файла Python.

Пример 4: строки документации модуля Python.

2. Строки документации для функций Python

Пример 5: строки документации для функций Python.

3. Строки документации для классов Python

Пример 6: строки документации для класса Python.

Предположим, у нас есть файл Person.py со следующим кодом:

Мы можем использовать следующий код для доступа только к строкам документации класса Person :

Использование функции help() для строк документации

Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.

Пример 7: чтение строк документации с помощью функции help().

Мы можем использовать функцию help() для класса Person из Примера 6:

Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.

4. Строки документации для скриптов Python

5. Строки документации для пакетов Python

Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.

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

Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.

Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.

Источник

Советы Google по кодированию на языке Python. Часть вторая: советы по форматированию исходного кода

Python Style Rules

Точки с запятой

Длина строки

Исключения

Когда Ваш текст не помещается в одну строку, используйте скобки для явного объединения строк.

Что касается комментариев, располагайте длинный URL, если это необходимо, на одной строке.

Обратите внимание на отступ элемента в строке выше (смотрите раздел про отступы, чтобы получить разъяснения).

Скобки

Не используйте их (скобки) с выражением return или с условной конструкцией, если не требуется организовать перенос строки. (Смотрите выше). Однако скобки хорошо использовать для создания кортежей.

Отступы

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

Пустые строки

Пробелы

Никаких пробелов внутри каких-либо скобок.
Хорошо: spam(ham[1], , [])
Плохо: spam( ham[ 1 ], < eggs: 2 >, [ ] )

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

Комментарии

Будьте уверены в использовании правильного стиля для модуля, функции, метода или строкового комментария.

Строки документации.

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

Модули

Каждый файл должен содержать в себе шаблон лицензии. Выберите подходящий шаблон лицензии для вашего проекта.(Например, Apache 2.0, BSD, LGPL, GPL).

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

Классы

Классы должны иметь строку документации ниже своего объявления. Если Ваш класс имеет публичные атрибуты, они должны быть документированы тут же в разделе Attributes и следовать тому же стилю форматирования, что и раздел Args.

Блоки и инлайновые комментарии

Последнее место, которое должны иметь комментарии — это хитрые места в коде. Если Вы хотите пояснить их в Вашем следующем код-ревью, то вы должны прокомментировать их сейчас. Сложные операции, занимающие несколько строк документации перед ее выполнением. Неявные части должны иметь комментарий в конце строки.

Чтобы улучшить читаемость, такие комменарии должны находиться на расстоянии по меньшей мере 2-х пробелов от кода. С другой стороны, лучше вообще не описывайте код. Преположите, что человек, читающий данный код, знает Python (а не то, что вы пытались делать) лучше, чем Вы.

Классы

Это также касается вложенных классов.

Наследование от класса object необходимо, чтобы позволить свойствам работать правильно, и защитит Ваш код от возможной несовместимости с Python 3000. В нем так же определяются специальные методы, которые реализуют стандартную семантику объекта, например: __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, и __str__.

Строки

Используйте оператор % для форматирования строк, даже если все параметры являются строками. Тщательно взвесте использование оператора + взамен оператора %.

Избегайте использования операторов + и +=, чтобы сконкатенировать строку при помощи цикла, т.к. строки — это неизменяемый тип данных, такой подход создает ненужные объекты и увеличивает время работы по квадратичному, а не линейному закону. Вместо этого просто добавьте каждую подстроку в список и используйте метод join после того, как цикл завершится ( или записывайте каждую подстроку в буфер cStringIO.StringIO)

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

Файлы и сокеты

Подобные циклу for объекты, которые не поддерживают конструкцию with и используют contextlib.closing()

Старый код, написанный под Python 2.5, может подключить возможность использования конструкции with при помощи импорта «from __future__ import with_statement«.

Комментарий TODO

Комментарии-TODO должны включать в себя строку TODO в начале каждого комментария, следующую за имменем, электронным адресом или другим идентификатором того, что лучше сможет обеспечить решение проблемы, указанной в скобках. Точка необязательна. Комментарий, объясняющий что там должно происходить, не требуется. Главная цель — это общий формат для TODO, который позволит быстро найти определенного челвоека, который сможет обеспечить более детальное описание проблемы. TODO не является залогом того, что человек решит данную проблему. Таким образом, когда Вы создаете TODO, он почти всегда содержит только Ваше имя.

Оформление импортов

Конструкции

Однако вы можете расположить результат текста на той же строке, на которой у Вас рапологается условие. Но это можно сделать только в том случае, когда все выражение помещается на одной строке. В частности, Вы никогда не сможете это сделать с конструкцией try/except, т.к. try и except не могут находиться в одной строке, и Вам доступно помещение в одну строку только с конструкцией if БЕЗ else.
Хорошо:

Контроль доступа

Именование

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_CONSTANT_NAME, global_var_name, instance_var_name, function_parameter_name, local_var_name.

Стили основаны на рекоммендациях Гвидо:

Даже когда файл создавался для того, чтобы быть импортированным, обычный импорт не должен иметь побочных эффектов в виде исполнения функциональной части скрипта. Основная функциональность должна быть заложена в функции main().
В Python, pychecker, pydoc и юнит тестах требуются импортируемые модули. Ваш код должен всегда проверять if __name__ == ‘__main__’ перед исполнением, что означает, что Ваш модуль не будет полностью исполнен при импортировании его в другую программу.

Весь код верхнего уровня будет исполнен, когда модуль будет импортирован. Будьте осторожны и не вызывайте функции, не создавайте объекта и не проводите другого вида операции, которые не должны будут выполняться, когда файл подвергнется проверке с помощью pychecker или будет собираться документация при помощи pydoc.

Заключительные слова

От переводчика

Благодарности

Огромное спасибо squaii за ревью и поиск ошибок.

Заключение

Источник