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

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

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

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

"""Модуль содержит классы плоских фигур."""
 
from math import pi, pow
 
 
class Rectangle:
    """Класс Прямоугольник.
Конструктор принимает длину и ширину."""
 
    def __init__(self, a, b):
        self.w = a
        self.h = b
 
    def square(self):
        """Метод для вычисления площади."""
        return round(self.w * self.h, 2)
 
    def perimeter(self):
        """Метод для вычисления периметра"""
        return 2 * (self.w + self.h)
 
 
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)
 

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

>>> from geometry import planimetry
>>> 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__', ...
>>> 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 – тоже вариант.

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

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

Курс с примерами решений практических работ и всеми уроками:
android-приложение, pdf-версия

Объектно-ориентированное программирование на Python