Зачем документировать и что такое docstring

Вы когда-нибудь открывали свой старый код через полгода и думали: «Кто это написал? Что это вообще делает?» Спойлер: это написали вы. В этом уроке разберёмся, как писать код, который будет понятен — и вам, и коллегам — через месяц, год и навсегда.

📖 Главный принцип: код читают чаще, чем пишут

Когда начинаешь программировать, кажется, что написать код — это самое главное. Нажал Run — работает, задача выполнена. Но в реальной разработке всё немного иначе.

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

Компьютеру всё равно, как вы назвали переменную и есть ли у функции описание. Он выполняет инструкции — и точка. Зато человеку, который будет читать ваш код через три месяца, совсем не всё равно.

🧠 «Будущий ты через полгода — это другой человек»

Это звучит немного философски, но это правда. Давайте разберёмся почему.

Посмотрите на простой пример. Угадайте, что делает эта функция:

def calc(x, y, z):
    return x * (1 - y / 100) if z else x

Что такое x? Что такое y? Что такое z? Когда возвращается x, а когда x * (1 - y / 100)? Чтобы понять — нужно читать весь код вокруг, искать где функция вызывается...

А теперь посмотрите на ту же функцию, но с документацией:

def apply_discount(price, discount_percent, is_sale):
    """
    Применяет скидку к цене товара.

    Если товар участвует в акции (is_sale=True),
    возвращает цену с учётом скидки.
    Иначе возвращает исходную цену без изменений.
    """
    return price * (1 - discount_percent / 100) if is_sale else price

Мгновенно понятно! Хорошее имя функции + докстринг — и никаких вопросов. Код говорит сам за себя.

👥 Командная разработка: твой код будут читать коллеги

Если вы работаете в команде — документирование становится ещё важнее. Ваш коллега не знает, что у вас было в голове, когда вы писали функцию. У него нет вашего контекста.

📝 Что такое docstring — строка-документация

Docstring (от англ. documentation string — строка документации) — это специальная строка, которую вы пишете сразу после объявления функции, метода, класса или модуля.

Ключевое слово здесь — «сразу после». Docstring — это не просто комментарий в произвольном месте. Это первая строка тела функции/класса/модуля. Именно это место делает её особенной — Python сам сохраняет её как часть объекта.

✍️ Синтаксис: тройные кавычки """..."""

Docstring записывается в тройных кавычках — либо двойных """...""", либо одинарных '''...'''. В Python принято использовать двойные.

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

Однострочный docstring — когда описание помещается в одну строку:

def greet(name):
    """Возвращает приветственное сообщение для пользователя."""
    return f"Привет, {name}!"

Многострочный docstring — когда нужно описать подробнее:

def calculate_area(width, height):
    """
    Вычисляет площадь прямоугольника.

    Принимает ширину и высоту в сантиметрах.
    Возвращает площадь в квадратных сантиметрах.
    """
    return width * height

🔬 Атрибут __doc__ — docstring живёт в объекте

Вот что делает docstring особенным — Python не просто «читает» эту строку и забывает. Он сохраняет её как атрибут объекта под именем __doc__. Это значит, что вы можете получить docstring в любой момент во время работы программы!

Двойные подчёркивания с обеих сторон (__doc__) — это в Python признак «магического» или «специального» атрибута. Такие атрибуты Python создаёт и использует сам. __doc__ — один из них.

def greet(name):
    """Возвращает приветственное сообщение для пользователя."""
    return f"Привет, {name}!"


# Получаем docstring через атрибут __doc__
print(greet.__doc__)
# Вывод: Возвращает приветственное сообщение для пользователя.


class Dog:
    """Класс, описывающий собаку с именем и породой."""

    def bark(self):
        """Заставляет собаку лаять."""
        return "Гав!"


# Docstring доступен и у класса, и у его методов
print(Dog.__doc__)
# Вывод: Класс, описывающий собаку с именем и породой.

print(Dog.bark.__doc__)
# Вывод: Заставляет собаку лаять.

📦 Docstring для класса и модуля

Docstring пишут не только для функций. Классы и целые файлы (модули) тоже документируют. Посмотрим на полный пример:

"""
Модуль для работы с банковскими счетами.

Содержит класс BankAccount с методами для пополнения,
снятия и проверки баланса.
"""


class BankAccount:
    """
    Банковский счёт с базовыми операциями.

    Позволяет хранить баланс и выполнять
    операции пополнения и снятия средств.
    """

    def __init__(self, owner, balance=0):
        """
        Создаёт новый банковский счёт.

        owner  — имя владельца счёта (строка)
        balance — начальный баланс (число, по умолчанию 0)
        """
        self.owner = owner
        self.balance = balance

    def deposit(self, amount):
        """Пополняет счёт на указанную сумму. Возвращает новый баланс."""
        self.balance += amount
        return self.balance

    def withdraw(self, amount):
        """
        Снимает деньги со счёта.

        Если средств недостаточно, вызывает ValueError.
        Возвращает новый баланс при успехе.
        """
        if amount > self.balance:
            raise ValueError("Недостаточно средств")
        self.balance -= amount
        return self.balance

Теперь доступ к документации:

import bank  # представим, что файл называется bank.py

print(bank.__doc__)
# Модуль для работы с банковскими счетами...

print(BankAccount.__doc__)
# Банковский счёт с базовыми операциями...

print(BankAccount.withdraw.__doc__)
# Снимает деньги со счёта...

🆘 Функция help() — удобный просмотр docstring

Python предоставляет встроенную функцию help(), которая показывает документацию объекта в красивом, читаемом виде. Именно из __doc__ атрибута она берёт информацию.

Вы можете вызвать help() прямо в интерпретаторе Python или в Jupyter Notebook — это очень удобно при изучении незнакомого кода.

def apply_discount(price, discount_percent, is_sale):
    """
    Применяет скидку к цене товара.

    Параметры:
        price           — исходная цена (число)
        discount_percent — размер скидки в процентах (число от 0 до 100)
        is_sale         — участвует ли товар в акции (True/False)

    Возвращает цену с учётом скидки, если is_sale=True.
    Иначе возвращает исходную цену без изменений.
    """
    return price * (1 - discount_percent / 100) if is_sale else price


# Вызываем help() в интерпретаторе:
help(apply_discount)

Вывод в интерпретаторе будет выглядеть вот так:

Help on function apply_discount in module __main__:

apply_discount(price, discount_percent, is_sale)
    Применяет скидку к цене товара.

    Параметры:
        price           — исходная цена (число)
        discount_percent — размер скидки в процентах (число от 0 до 100)
        is_sale         — участвует ли товар в акции (True/False)

    Возвращает цену с учётом скидки, если is_sale=True.
    Иначе возвращает исходную цену без изменений.

⚖️ Docstring vs комментарий — в чём разница

В Python есть два способа оставить текстовое пояснение к коду: комментарий через # и docstring через """...""". Многие новички считают их одинаковыми — но между ними принципиальная разница.

Смотрите на примере — как они живут вместе:

def calculate_tax(price, rate):
    """Вычисляет сумму налога для заданной цены и ставки."""
    # rate — это процент, поэтому делим на 100
    # например rate=20 означает НДС 20%
    return price * rate / 100


# Docstring сохранён и доступен:
print(calculate_tax.__doc__)
# Вывод: Вычисляет сумму налога для заданной цены и ставки.

# А комментарии — нет, они исчезли при выполнении:
# print(calculate_tax.comments)  <-- такого атрибута не существует

✅ Где обязательно писать docstring

Docstring — это хороший тон, но не всегда обязательный. Вот чёткое правило: если что-то «публичное» (то есть предназначено для использования другими), — docstring обязателен.

✅ Итоги урока

• Код читается чаще, чем пишется — пишите для людей: для коллег, для себя будущего, для тех, кто будет поддерживать ваш код.
• «Будущий ты через полгода — другой человек»: без документации вы сами не поймёте свой код через несколько месяцев.
• Docstring — это строка в тройных кавычках """...""", которая пишется сразу после объявления функции, класса или модуля.
• Атрибут __doc__: Python сохраняет docstring как часть объекта — его можно прочитать в любой момент через obj.__doc__.
• help(obj) показывает docstring в красивом виде — именно так работает документация стандартной библиотеки Python.
• Docstring ≠ комментарий: комментарий (#) исчезает при выполнении, docstring живёт в объекте. Комментарий объясняет как, docstring объясняет что.
• Писать docstring обязательно для всех публичных классов, методов и функций — это профессиональный стандарт.

👉 В следующем уроке мы познакомимся с форматом Google Style docstring — наиболее популярным соглашением в современном Python-коде. Вы научитесь описывать параметры, возвращаемые значения и исключения так, как это делают в Google, Яндексе и других крупных компаниях.