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

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

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

В Python строки документации окружены тройными кавычками и располагаются непосредственно под заголовком объекта. Пример документированного модуля приведён ниже:

"""Модуль содержит классы плоских фигур."""

from math import pi, pow

class Rectangle:
    """Класс Прямоугольник.
Конструктор принимает длину и ширину."""
    def __init__(self, a, b):
        self.width = a
        self.height = b
    def square(self):
        """Метод для вычисления площади прямоугольника."""
        return round(self.width * self.height, 2)
    def perimeter(self):
        """Метод для вычисления периметра прямоугольника."""
        return 2 * (self.width + self.height)

class  Circle:
    """Класс Круг.
Конструктор принимает радиус."""
    def __init__(self, radius):
        self.r = radius
    def square(self):
        """Метод для вычисления площади круга."""
        return round(pi * pow(self.r, 2), 2)
    def length(self):
        """Метод для вычисления длины окружности."""
        return round(2 * pi * self.r)

Отобразить строки документации можно двумя способами:

• Через встроенный атрибут __doc__ каждого объекта.
• Используя встроенную функцию help(), которая предоставляет справочную информацию в интерактивном режиме.

>>> from geometry import planimetry
>>> planimetry.Rectangle.b__doc__
'Класс Прямоугольник.\nКонструктор принимает длину и ширину.'
>>> print(planimetry.Rectangle.__doc__)
Класс Прямоугольник.
Конструктор принимает длину и ширину.
>>> print(planimetry.__doc__)
Модуль содержит классы плоских фигур.

Команда help(planimetry) вызывает отображение всех строк документации модуля в структурированном формате. Также можно запросить справку по конкретным объектам:

>>> help(planimetry.Circle.length)
Help on function length in module geometry.planimetry:

length(self)
    Метод для вычисления длины окружности.

Чтобы выйти из режима справки, нажмите клавишу q.

В Python все встроенные объекты и модули библиотеки содержат документы.

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.
>>> import math
>>> dir(math)
['__doc__', '__loader__', '__name__', '__package__', '__spec__', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'ceil', 'copysign', 'cos', 'cosh', 'degrees', 'e', 'erf', 'erfc', 'exp', 'expm1', 'fabs', 'factorial', 'floor', 'fmod', 'frexp', 'fsum', 'gamma', 'gcd', 'hypot', 'inf', 'isclose', 'isfinite', 'isinf', 'isnan', 'ldexp', 'lgamma', 'log', 'log10', 'log1p', 'log2', 'modf', 'nan', 'pi', 'pow', 'radians', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'trunc']
>>> print(math.trunc.__doc__)
trunc(x:Real) -> Integral

Truncates x to the nearest Integral toward 0. Uses the __trunc__ magic method.

Таким образом, если вам необходимо узнать назначение функции и принцип её работы, это можно сделать, не выходя из интерпретатора Python. Перечень атрибутов и методов модуля легко доступен через функцию dir().

Также важно отметить, что документирование модулей традиционно выполняется на английском. Открытый код многих проектов расположен в интернете для общего доступа и редактируется разработчиками со всего мира. Использование одного языка помогает этим специалистам понимать друг друга. Таким образом, владение английским, хотя бы на базовом уровне, является важным навыком для профессионального программиста. Где необходимо, вы всегда можете воспользоваться Google Translate.

Практическая работа

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