Skip to content

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

В Python документация — это не просто комментарии для человека. Это структурированные строки (docstrings), которые формируют встроенную справку, отображаются в IDE при наведении на методы и могут автоматически превращаться в полноценные сайты.

Из этого урока вы узнаете, как оформлять документацию в самом читаемом Google Style, документировать уровни доступа (публичные, защищенные, приватные) и писать интерактивные примеры.

1. Стили Docstrings: Почему именно Google Style? ​

В Python-сообществе существует три основных стандарта:

  1. Google Style: Самый читаемый и популярный стиль. Использует понятные текстовые отступы и секции (Args:, Returns:, Attributes:).
  2. NumPy Style: Более развернутый стиль, где заголовки секций подчеркиваются дефисами. Часто применяется в data science.
  3. Sphinx / ReStructuredText (reST) Style: Стандартный стиль для генератора документации Sphinx. Использует синтаксис двоеточий (например, :param x:). Менее читаем в сыром виде, но отлично парсится.

Мы будем изучать Google Style, так как он признан самым сбалансированным: он легко читается человеком прямо в текстовом редакторе и при этом идеально парсится автоматическими генераторами.

Базовые секции Google Style: ​

  • Attributes: — для описания свойств класса.
  • Args: — для аргументов функций и методов.
  • Returns: — для возвращаемых значений.
  • Raises: — для перечисления возможных ошибок (исключений).
py
class PaymentProcessor:
    """Процессор для управления финансовыми транзакциями пользователей.

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

    Attributes:
        is_active (bool): Публичный флаг доступности процессора.
        _gateway_timeout (int): Защищенный (protected) таймаут соединения в секундах.
        __encryption_key (str): Приватный (private) ключ для подписи транзакций.
    """

    def __init__(self, gateway_timeout: int = 30) -> None:
        """Инициализирует процессор платежей.

        Args:
            gateway_timeout (int): Время ожидания ответа от шлюза.
        """
        # 1. Публичный атрибут (доступен везде)
        self.is_active: bool = True

        # 2. Защищенный атрибут (на уровне соглашения: для подклассов и модуля)
        self._gateway_timeout: int = gateway_timeout

        # 3. Приватный атрибут (инкапсулирован внутри класса через Name Mangling)
        self.__encryption_key: str = "SECRET_HEX_KEY_123"

    def process_payment(self, account_id: str, amount: float) -> bool:
        """Публичный метод: Проводит транзакцию для указанного аккаунта.

        Используется внешним кодом для инициации оплаты.

        Args:
            account_id (str): Уникальный идентификатор пользователя.
            amount (float): Сумма списания (должна быть строго больше 0).

        Returns:
            bool: True, если платеж успешно проведен, иначе False.

        Raises:
            ValueError: Если сумма `amount` меньше или равна нулю.
        """
        if amount <= 0:
            raise ValueError("Сумма транзакции должна быть положительной.")
        
        # Вызов защищенного метода
        return self._connect_to_gateway(account_id, amount)

    def _connect_to_gateway(self, account_id: str, amount: float) -> bool:
        """Защищенный метод: Устанавливает соединение со шлюзом.

        Предназначен для внутреннего использования и переопределения в наследниках.

        Args:
            account_id (str): Идентификатор аккаунта.
            amount (float): Сумма для отправки в шлюз.

        Returns:
            bool: Статус ответа сервера.
        """
        # Логика подключения...
        # Вызов приватного метода для подписи данных
        signature = self.__sign_data(f"{account_id}:{amount}")
        return True

    def __sign_data(self, data: str) -> str:
        """Приватный метод: Шифрует данные перед отправкой.

        Доступен строго внутри этого класса. Защищает критическую логику.

        Args:
            data (str): Строка сырых данных для подписи.

        Returns:
            str: Хэш-подпись в формате строки.
        """
        # Логика шифрования с использованием self.__encryption_key
        return f"signed_{data}"

Основные правила оформления для Python:

• Где описывать свойства (Attributes): Публичные и защищенные атрибуты класса принято перечислять в блоке Attributes: внутри docstring самого класса, а не внутри __init__. • Приватные атрибуты и методы: Технически, писать подробную документацию к приватным элементам (с __) для внешних пользователей не нужно, так как они скрыты внутри класса. Однако для разработчиков, которые будут поддерживать ваш код, их документируют точно так же (через краткое описание аргументов и возвращаемого значения).

Какие еще секции могут быть в Docstrings? ​

Ниже представлены основные дополнительные секции, расположенные в логическом порядке их применения: • Raises: (или Yields: для генераторов) — перечень всех исключений, которые метод может намеренно выбросить, и условия, при которых это происходит. • Example: или Examples: — секция для демонстрации работы кода (здесь и размещаются примеры). • Note: — важные примечания, особенности поведения метода или скрытые нюансы, о которых должен знать разработчик. • Warning: — предупреждения о потенциально опасных действиях (например, «метод удаляет данные без возможности восстановления» или «метод не потокобезопасен»). • Todo: — временные метки для планирования будущих доработок (многие IDE подсвечивают их автоматически). • Deprecated: — указание на то, что метод устарел, с рекомендацией, чем его заменить.

Примеры кода оформляются в секции Examples:. Чтобы генераторы документации правильно их форматировали, а встроенный модуль Python doctest мог их тестировать, код записывают так, будто вы вводите его в интерактивной консоли Python (используя символы >>> для строк кода и следующую строку для ожидаемого вывода).

Полный пример класса со всеми секциями:

py
class Calculator:
    """Простой калькулятор для демонстрации расширенных секций документации.

    Attributes:
        precision (int): Количество знаков после запятой для округления.
    """

    def __init__(self, precision: int = 2) -> None:
        self.precision: int = precision

    def divide(self, dividend: float, divisor: float) -> float:
        """Делит одно число на другое с заданным округлением.

        Args:
            dividend (float): Делимое число.
            divisor (float): Делитель (не должен быть равен нулю).

        Returns:
            float: Результат деления, округленный до `precision` знаков.

        Raises:
            ZeroDivisionError: Если `divisor` равен 0.

        Note:
            В Python деление float может приводить к незначительным погрешностям 
            из-за специфики архитектуры процессора, поэтому применяется округление.

        Warning:
            Передача слишком больших чисел может замедлить вычисления 
            на некоторых старых платформах.

        Examples:
            >>> calc = Calculator(precision=2)
            >>> calc.divide(10, 3)
            3.33
            >>> calc.divide(5, 2)
            2.5

        Todo:
            * Добавить поддержку комплексных чисел в следующей версии.
            * Интегрировать логирование ошибок деления на ноль.
        """
        if divisor == 0:
            raise ZeroDivisionError("Деление на ноль строго запрещено.")
        
        return round(dividend / divisor, self.precision)

2. Комплексный пример: Оформление класса ​

Давайте разберем класс, в котором задействованы все виды видимости атрибутов и методов, а также расширенные секции документации.

python
class SmartTermostat:
    """Управляющий модуль системы климат-контроля умного дома.

    Этот класс инкапсулирует логику работы с датчиками температуры,
    проверку пороговых значений и безопасное переключение режимов.

    Attributes:
        room_name (str): Публичное имя комнаты.
        is_on (bool): Флаг активности термостата.
        _target_temp (float): Защищенный (protected) целевой показатель температуры.
        __hardware_id (str): Приватный (private) серийный номер устройства.
    """

    def __init__(self, room_name: str, target_temp: float = 22.0) -> None:
        """Инициализирует термостат для конкретной комнаты.

        Args:
            room_name (str): Название помещения (например, 'Гостиная').
            target_temp (float): Желаемая температура по умолчанию.
        """
        self.room_name: str = room_name
        self.is_on: bool = False
        self._target_temp: float = target_temp
        self.__hardware_id: str = "HW-9982X-BASE"

    def set_temperature(self, temperature: float) -> bool:
        """Публичный метод: Безопасно изменяет целевую температуру.

        Используется внешними контроллерами или интерфейсом пользователя.

        Args:
            temperature (float): Новое значение в градусах Цельсия.

        Returns:
            bool: True, если температура успешно изменена, иначе False.

        Raises:
            ValueError: Если температура выходит за рабочий диапазон (от 15 до 30 градусов).

        Note:
            Изменение температуры не сработает, если термостат выключен (`is_on = False`).

        Examples:
            >>> term = SmartTermostat("Спальня", target_temp=21.0)
            >>> term.is_on = True
            >>> term.set_temperature(24.5)
            True
            >>> term.set_temperature(45.0)
            Traceback (most recent call last):
                ...
            ValueError: Температура 45.0 выходит за рамки лимитов (15-30°C).
        """
        if not self.is_on:
            return False

        if not (15.0 <= temperature <= 30.0):
            raise ValueError(f"Температура {temperature} выходит за рамки лимитов (15-30°C).")

        self._target_temp = temperature
        self._log_change(f"Установлена температура: {temperature}")
        return True

    def _log_change(self, message: str) -> None:
        """Защищенный метод: Записывает изменения состояния в логи.

        Предназначен для внутреннего использования и переопределения в подклассах.

        Args:
            message (str): Текст сообщения для лога.
        """
        print(f"[LOG] [{self.room_name}] {message}")

    def __generate_signature(self) -> str:
        """Приватный метод: Создает зашифрованную подпись устройства.

        Используется строго внутри этого класса для синхронизации с сервером.

        Returns:
            str: Уникальный хэш устройства.
        """
        return f"encrypted_{self.__hardware_id}"

Свойства и уровни доступа

  1. Публичные и защищенные (_) атрибуты выносятся в общую секцию Attributes: класса. Приватные (__) атрибуты чаще всего документируют там же, если они критически важны для понимания работы наследников, либо опускают (так как они скрыты внутри класса).
  2. Методы документируются индивидуально. Полнота секций для защищенных и приватных методов определяется тем, насколько сложная у них внутренняя логика. Описание аргументов и возвращаемых типов строго обязательно для всех.

Пример: класс ParcelBox ​

Hero-класс модуля, оформленный в Google Style:

python
class ParcelBox:
    """Класс, представляющий почтовую коробку для отправки посылок.

    Хранит размеры коробки и вес посылки, защищает значения
    от некорректных изменений и предоставляет доступ к вычисленному объёму.

    Attributes:
        length (float): Длина коробки в сантиметрах.
        width (float): Ширина коробки в сантиметрах.
        height (float): Высота коробки в сантиметрах.
        weight (float): Вес посылки в граммах.
    """

    def __init__(self, length: float, width: float, height: float, weight: float = 0.0) -> None:
        """Инициализирует коробку.

        Args:
            length (float): Длина в сантиметрах.
            width (float): Ширина в сантиметрах.
            height (float): Высота в сантиметрах.
            weight (float): Вес посылки в граммах.

        Raises:
            ValueError: Если любое измерение или вес отрицательно.
        """
        for name, value in (('length', length), ('width', width), ('height', height), ('weight', weight)):
            if value < 0:
                raise ValueError(f'Параметр {name} не может быть отрицательным: {value}')
        self.length: float = length
        self.width: float = width
        self.height: float = height
        self.weight: float = weight

    def get_volume(self) -> float:
        """Возвращает объём коробки в кубических сантиметрах.

        Returns:
            float: Объём коробки (length * width * height).
        """
        return self.length * self.width * self.height


box = ParcelBox(10.0, 5.0, 2.0, weight=250.0)
print(box.get_volume())   # 100.0
# box = ParcelBox(-1, 5, 2)  # ValueError

Описание кода:

  • Attributes: — публичные атрибуты перечислены в docstring класса: тип и назначение в одном месте.
  • Args: — аргументы __init__ описаны с типами в скобках.
  • Raises: — явно указано, когда поднимается ValueError.
  • Returns: — у get_volume описано возвращаемое значение и единицы измерения.
  • Аннотации : float, -> None, -> float уточняют типы и проверяются статическими анализаторами.

3. Интерактивные примеры: Модуль doctest ​

Обратите внимание на секцию Examples: в методе set_temperature. Строки, начинающиеся с >>>, имитируют консоль Python.

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

python
if __name__ == "__main__":
    import doctest
    doctest.testmod(verbose=True)

Тестирование исключений в Doctest

При написании примера, который должен выдать ошибку (как в примере выше с ValueError), используйте многоточие ... вместо вывода всего длинного стека вызовов (Traceback). doctest проверяет только первую строку ошибки и последнюю.

4. Документирование свойств с декоратором @property ​

Использование декоратора @property — стандартный способ реализации геттеров и сеттеров в Python. При работе с ними важно соблюдать два ключевых правила документирования:

  1. Где писать основную документацию: Вся подробная информация (описание, типы данных, секции Raises: и Examples:) пишется внутри геттера (метода, над которым стоит просто @property).
  2. Нужно ли документировать сеттер: Сеттер (@property_name.setter) обычно не требует отдельной строки документации, если его поведение очевидно и совпадает с геттером. Документировать сеттер нужно только в том случае, если он выполняет сложную валидацию или выбрасывает специфические исключения, которые не упомянуты в геттере.

Пример документирования свойств ​

Рассмотрим класс SmartWindow, управляющий процентом открытия автоматического окна:

python
class SmartWindow:
    """Управление автоматическим окном умного дома.

    Attributes:
        room (str): Название комнаты.
    """

    def __init__(self, room: str) -> None:
        self.room: str = room
        self._open_percentage: float = 0.0  # Защищенный атрибут

    @property
    def open_percentage(self) -> float:
        """float: Процент открытия окна (от 0.0 до 100.0).

        Эта строка документации описывает само свойство. Обратите внимание,
        что в начале строки принято указывать тип данных свойства.

        Raises:
            ValueError: Если при установке значения передан процент вне диапазона.

        Examples:
            >>> window = SmartWindow("Кухня")
            >>> window.open_percentage
            0.0
            >>> window.open_percentage = 50.5
            >>> window.open_percentage
            50.5
        """
        return self._open_percentage

    @open_percentage.setter
    def open_percentage(self, value: float) -> None:
        # Отдельный docstring здесь не нужен, так как вся логика описана в геттере.
        # Но если логика сеттера сложная, здесь документируют только специфику валидации.
        if not (0.0 <= value <= 100.0):
            raise ValueError("Процент открытия должен быть в диапазоне от 0.0 до 100.0")
        
        self._open_percentage = value

Свойства в блоке Attributes: класса

Если вы подробно задокументировали свойство через @property, дублировать его в секции Attributes: в описании самого класса не нужно. Автоматические генераторы документации (например, Sphinx) сами найдут декоратор @property и вынесут его в правильный раздел на веб-странице.

Проверьте себя ​

❓Что такое docstring в Python?
❓Почему в уроке выбран именно Google Style?
❓Какая секция Google Style описывает атрибуты класса?
❓Как модуль `doctest` проверяет документацию?
❓Что писать в doctest-примере, который должен выбросить ошибку?
❓Где пишется основная документация свойства `@property`?

Упражнения ​

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

Упражнение 1: Документирование класса "Банковский Аккаунт" ​

Создайте класс BankAccount со следующей структурой и полностью задокументируйте его в Google Style:

  • Атрибуты:
    • owner (str, публичный)
    • _balance (float, защищенный)
    • __pin_code (int, приватный)
  • Методы:
    • deposit(amount: float) -> None (публичный) — увеличивает баланс. Выбрасывает ValueError, если сумма отрицательная.
    • _validate_transaction(amount: float) -> bool (защищенный) — проверяет лимиты.

Обязательное условие

Класс должен содержать секции Attributes:, Args:, Raises: и Note: (объясните в примечании, почему баланс защищен от прямого изменения).

Упражнение 2: Написание "Живой" документации (Doctest) ​

Возьмите класс Calculator или любую простую функцию (например, вычисление факториала) и напишите для нее метод multiply(a, b).

  1. Добавьте секцию Examples: с двумя успешными тестами.
  2. Подключите модуль doctest и запустите скрипт через терминал: python имя_файла.py.
  3. Убедитесь, что тесты проходят успешно (Test passed).

Упражнение 3: Документирование свойств (@property) и валидации ​

Создайте класс Product, представляющий товар в интернет-магазине. Задокументируйте его строго по стандартам Google Style.

  • Внутреннее состояние:
    • _price (float, защищенный атрибут) — базовая цена товара.
  • Свойства (@property):
    • price — геттер возвращает текущую цену. Добавьте подробное описание свойства, указав тип данных (float:) на первой строке docstring.
    • Сеттер price должен проверять, что устанавливаемая цена — положительное число (строго больше нуля). Если условие нарушено, выбрасывается ValueError.
  • Примеры кода (Examples:):
    • Внутри геттера напишите интерактивный пример использования: создание товара с ценой 100.0, успешное изменение цены на 120.0 и попытку установить цену -50.0, которая должна приводить к ошибке ValueError.

Подсказка по оформлению

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

Упражнение 4: Комплексный финал — Класс "Умная Батарея" ​

Это продвинутое упражнение объединяет все изученные элементы: уровни доступа, секции Raises, Note, Warning и тестирование doctest.

Создайте класс SmartBattery, моделирующий аккумулятор мобильного устройства:

  1. Атрибуты класса:
    • capacity (int, публичный) — общая емкость в мАч.
    • _charge_level (int, защищенный) — текущий заряд в процентах (от 0 до 100).
    • __cycle_count (int, приватный) — количество циклов перезарядки.
  2. Методы:
    • charge(amount: int) -> None (публичный) — увеличивает _charge_level.
      • Если уровень достигает 100, __cycle_count увеличивается на 1.
      • Если передано отрицательное число, выбрасывает ValueError.
  3. Требования к документации:
    • Задокументируйте класс полностью. В секцию Attributes: вынесите публичный и защищенный атрибуты.
    • Для метода charge добавьте секцию Warning:, предупреждающую, что частая зарядка до 100% ускоряет деградацию литий-ионного аккумулятора.
    • Добавьте секцию Examples:, в которой сымитируйте зарядку аккумулятора со 95% до 100% и проверьте, как это влияет на логику.

Шаблоны для самопроверки и решения (Ответы) ​

Вы можете развернуть блоки ниже, чтобы сверить свой код с эталонным решением.

Посмотреть решение Упражнения 3 (Product)
python
class Product:
    """Товарная единица торговой площадки."""

    def __init__(self, initial_price: float) -> None:
        if initial_price <= 0:
            raise ValueError("Начальная цена должна быть больше нуля.")
        self._price: float = initial_price

    @property
    def price(self) -> float:
        """float: Актуальная стоимость товара в валюте магазина.

        Raises:
            ValueError: Если совершена попытка установить цену, равную 
                или меньшую нуля.

        Examples:
            >>> prod = Product(100.0)
            >>> prod.price
            100.0
            >>> prod.price = 120.5
            >>> prod.price
            120.5
            >>> prod.price = -5.0
            Traceback (most recent call last):
                ...
            ValueError: Цена товара должна быть строго положительной.
        """
        return self._price

    @price.setter
    def price(self, value: float) -> None:
        if value <= 0:
            raise ValueError("Цена товара должна быть строго положительной.")
        self._price = value
Посмотреть решение Упражнения 4 (SmartBattery)
python
class SmartBattery:
    """Модель аккумуляторной батареи с контролем износа.

    Attributes:
        capacity (int): Номинальная емкость батареи в мАч.
        _charge_level (int): Текущий уровень заряда в процентах (0-100).
    """

    def __init__(self, capacity: int) -> None:
        self.capacity: int = capacity
        self._charge_level: int = 50
        self.__cycle_count: int = 0

    def charge(self, amount: int) -> None:
        """Заряжает аккумулятор на указанное количество процентов.

        Args:
            amount (int): Количество процентов для добавления.

        Raises:
            ValueError: Если передано отрицательное значение `amount`.

        Warning:
            Постоянное поддержание заряда на уровне 100% или глубокий разряд 
            до 0% ускоряют химическую деградацию ячеек.

        Examples:
            >>> battery = SmartBattery(4500)
            >>> battery._charge_level = 95
            >>> battery.charge(5)
            >>> battery._charge_level
            100
            >>> battery.charge(-10)
            Traceback (most recent call last):
                ...
            ValueError: Значение зарядки не может быть отрицательным.
        """
        if amount < 0:
            raise ValueError("Значение зарядки не может быть отрицательным.")
        
        self._charge_level = min(100, self._charge_level + amount)
        
        if self._charge_level == 100:
            self.__cycle_count += 1

Чек-лист самопроверки ​

Перед отправкой кода на ревью проверьте себя:

  • [ ] Описание класса начинается с заглавной буквы и точки на первой строке.
  • [ ] Все публичные и защищенные атрибуты перечислены в Attributes: класса.
  • [ ] Названия секций (Args:, Returns:, Raises:) написаны с большой буквы и заканчиваются двоеточием.
  • [ ] Аргументы в секции Args: содержат указание типа в скобках, например amount (float): ...
  • [ ] Интерактивные примеры используют префикс >>>. Перед тем как завершить работу над этим модулем, убедитесь, что вы:
  • [ ] Понимаете разницу между описанием атрибутов в теле класса и описанием @property.
  • [ ] Знаете, как запустить проверку doctest через терминал вашего окружения.
  • [ ] Оформляете многострочные блоки исключений Traceback (most recent call last): с использованием символов ... для сокращения вывода.