Комментарии и docstrings в Python: правила и примеры

Развернутое объяснение

Комментарии в Python начинаются с символа # и продолжаются до конца строки. Интерпретатор их игнорирует, они нужны только людям, читающим код.

Основные принципы написания комментариев:

Комментарий должен объяснять зачем написан данный код, а не повторять то, что и так видно из кода.\
Строка комментария начинается с # и пробела, написана как связное предложение с заглавной буквы.
Длина строки комментария — до ~72 символов, чтобы текст удобно читался в редакторах и терминалах.

Примеры:

# Пересчитываем баланс с учетом отменённых транзакций
balance = calculate_balance(transactions)
x = x + 1  # Компенсируем погрешность округления

Не стоит писать очевидное:

i = 0  # устанавливаем i в ноль  # лишний комментарий

Такие практики мы сразу внедряем в учебных проектах TeoBrain: студенты учатся писать комментарии там, где они реально помогают следующему разработчику.

Docstrings: документация прямо в коде

Docstring — это строковый литерал в тройных кавычках """...""" (или '''...'''), который находится сразу после объявления модуля, функции, класса или метода.

Пример для функции:

def send_email(to, subject, body):
   """Send email message to specified recipient.
   Parameters:
       to (str): Recipient email address.
       subject (str): Email subject line.
       body (str): Plain text message body.
   """
   ...

Docstring отвечает на вопрос что в целом делает объект, а не как это пошагово реализовано. Его можно увидеть при вызове функции интерактивной помощи (help(send_email)) или через атрибут __doc__, поэтому он является частью публичного интерфейса. PEP 8 рекомендует писать docstring’и для всех публичных модулей, классов, функций и методов. PEP 257 описывает структуру:

Однострочный docstring — краткая фраза, заканчивающаяся точкой.

Многострочный — первая строка‑резюме, затем пустая строка и более подробное описание, включая параметры, возвращаемые значения, возможные исключения.

Это критически важно для больших backend‑проектов: docstring’и используются генераторами документации, IDE и коллегами, которые читают ваш код.

Комментарии и docstring’и: когда что использовать?

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

Как писать комментарии и docstrings?