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

Важным моментом в программировании на python является документирование кода, так как от этого зависит понимание вашего кода другими людьми и даже вами самими спустя некоторое время.

PEP 257 представляет собой руководство по стилю, касающееся строк документации в Python, и объясняет правила оформления документации для кода на Python.

Задача данного PEP заключается в унификации формата строк документации: определение их составляющих и рекомендации по их написанию (без углубления в вопросы синтаксиса). Данный PEP представляет собой набор соглашений, а не жестких правил или синтаксиса.

Если вы нарушите эти соглашения, то единственное, что вас ждет - недовольные взгляды. Однако некоторые программы (например, docutils) придерживаются этих соглашений, поэтому их соблюдение принесет вам наилучшие результаты.

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

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

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

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

Существует два вида документации: однострочная и многострочная форма записи.

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

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

def kos_root(): """Return the pathname of the KOS root directory.""" global _kos_root if _kos_root: return _kos_root

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

Лучше располагать закрывающие кавычки на той же строке. Это придает тексту более аккуратный вид.

Не допускается наличие лишних пробелов перед или после описания.

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

def function(a, b): """function(a, b) -> list"""

Данный формат документации применим исключительно к функциям на языке C (например, встроенные модули), где невозможно использовать интроспекцию. Однако возвращаемое значение не может быть определено с помощью интроспекции. Рекомендуемым вариантом для такой документации будет следующее:

def function(a, b): """Do X and return a list."""

(Конечно, вместо "Do X" лучше использовать информативное описание!)

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

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

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

Для обеспечения удобства использования программы, строки документации скрипта должны быть доступны в качестве сообщения при вызове программы с некорректными или отсутствующими аргументами, либо при использовании опции "-h" для получения помощи. Эти строки документации должны содержать информацию о функциях программы, синтаксисе командной строки, переменных окружения и файлах. Сообщение по использованию может быть довольно объемным и должно быть достаточно понятным для новых пользователей, чтобы они могли правильно использовать программу. Также оно должно содержать полный справочник со всеми возможными вариантами и аргументами для опытных пользователей.

Обычно в документации модуля перечисляются классы, исключения, функции и другие объекты, которые модуль экспортирует, с краткими пояснениями каждого из них в одну строчку. Эти описания обычно содержат меньше информации, чем первая строка документации к объекту. Документация пакета модулей (т.е. строка документации в __init__.py) также должна включать модули и подпакеты.

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

Описание класса содержит обобщенную информацию о его функциональности, перечисление публичных методов и переменных экземпляра. Если класс предназначен для наследования и имеет специфический интерфейс для подклассов, этот интерфейс должен быть отдельно указан в описании. Конструктор класса должен быть задокументирован в документации метода __init__. Каждый метод должен иметь свое собственное описание.

Если класс является подклассом другого класса и в основном наследует его поведение, необходимо в строках документации отметить это и обобщить различия. Для указания того, что метод подкласса заменяет метод суперкласса и не вызывает его, используйте глагол "override"; для указания того, что метод подкласса вызывает метод суперкласса (наряду со своим собственным поведением), используйте глагол "extend".

В заключение, вот пример:

def complex(real=0.0, imag=0.0): """Form a complex number.

Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)

""" if imag == 0.0 and real == 0.0: return complex_zero ...

Еще больше примеров можно найти в стандартной библиотеке Python, например, в директории Lib вашего Python-интерпретатора.