Поскольку в языках программирования, в том числе 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)
Извлекать строки документации можно двумя способами:
- Через встроенный для каждого объекта атрибут-переменную __doc__.
- С помощью встроенной в Python функции help(), которая запускает интерактивную справочную систему.
>>> 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-версия
Источник:https://younglinux.info/