Комментарии в Python: однострочные, многострочные и docstring-и

Комментарии — для людей

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

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

Однострочные комментарии через #

Базовая форма — #, за которым идёт твоя заметка:

Можно прицепить короткий комментарий к концу строки. По соглашению оставляй минимум два пробела перед #:

Python читает # в любом месте вне строки и воспринимает остаток строки как комментарий. Уточнение «вне строки» важно: # внутри кавычек — это просто символ.

#section-2 внутри строки — часть URL. Python переключается в режим «комментарий» только на том #, который идёт после закрытия строки.

Комментирование нескольких строк

У Python нет блочного комментария /* */. Чтобы пропустить несколько строк, ставь # в начале каждой:

Руками эти # почти никогда не набивают. У любого приличного редактора есть шорткат «переключить комментарий на строке», добавляющий или удаляющий # на каждой выделенной строке:

• VS Code: Cmd + / (macOS) или Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / или Ctrl + /
• Vim: зависит от плагинов; vim-commentary биндит gcc на одну строку и gc на выделение.

Выучи этот шорткат в своём редакторе один раз — и «закомментирую этот блок, попробую иначе» становится операцией в один клавишный жест.

Трюк с тройными кавычками (и почему это не настоящий комментарий)

Иногда будешь видеть такое:

Формально это строковое выражение, которое выбрасывается. Python парсит его, вычисляет, отбрасывает результат. Ведёт себя как комментарий, но комментарием не является. Стилистически это хорошая идея только в одном конкретном месте — в качестве docstring-а.

Docstring-и: единственное правильное место для тройных кавычек

Docstring — это строка в тройных кавычках, поставленная самой первой инструкцией в функции, классе или модуле. Python распознаёт её как документацию и делает доступной во время выполнения через функцию help() и атрибут __doc__:

Две причины, почему docstring-и удобны:

1. Инструменты вроде IDE, help() и генераторов документации читают их автоматически. Комментарий над функцией ничего подобного не получает.
2. Они описывают функцию в точке вызова — когда кто-то наводит на discount(...) в редакторе, docstring всплывает подсказкой.

Есть соглашение (PEP 257), что положено в docstring: однострочная сводка на первой строке, пустая строка, потом более длинное описание, если нужно. Не заморачивайся точным форматом в первый день — простая однострочная версия всё равно гораздо лучше, чем никакой.

О чём на самом деле говорят хорошие комментарии

Пара ориентиров, которые сэкономят много головной боли в будущем:

• Предпочитай «почему», а не «что». # Loop over the users — шум; # Retry on 503 — Redis sometimes dies mid-deploy — золото.
• Обновляй комментарии, когда меняешь код. Неправильный комментарий хуже, чем отсутствие. Устаревший комментарий активно вводит в заблуждение.
• Не оставляй закомментированный код лежать. Не нужен — удаляй. Система контроля версий помнит. Файл, усыпанный закомментированными блоками, быстро теряет доверие.
• Пропускай очевидное. x = x + 1 # increment x не добавляет ничего.

Итог

Комментарии бесплатно писать и дёшево пропускать. Обращайся к ним, когда оставляешь читателю заметку, за которую он тебя поблагодарит: неочевидную причину, почему что-то работает, ссылку на issue, предупреждение о краевом случае. Используй docstring-и, когда определяешь функцию или класс. В остальном пусть говорят за тебя ясные имена и маленькие функции.

Теперь у тебя есть всё, чтобы читать и писать Python-файл. Следующая глава — там, где язык по-настоящему начинает что-то делать: переменные, типы данных и значения, которые Python умеет хранить.