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

Поскольку в языках программирования, в том числе 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__.

  • С помощью встроенной в Python функции help(), которая запускает интерактивную справочную систему.

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

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

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

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

Создано

Обновлено