Курс Python → Многострочные комментарии в Python

Речь пойдет о том, как в Python сделать многострочный комментарий. В отличие от некоторых других языков, где есть специальный синтаксис типа /*…*/, в Python такого прямого инструмента нет. Но это не значит, что мы совсем беззащитны! Есть два основных способа, как можно это обойти, и оба они довольно простые, когда разберешься. Один — это просто куча однострочных комментариев, а второй — использование строковых литералов в тройных кавычках. Ну, и про то, как это всё работает, и почему это важно для документирования кода, мы сейчас и поговорим.

Честно говоря, когда я сам начинал, тоже ломал голову, как бы красиво и объемно что-нибудь прокомментировать. И тут выясняется, что Python предлагает пару таких неочевидных, но рабочих решений. Наша задача — понять, когда что лучше использовать, чтобы ваш код был не просто рабочим, а еще и понятным для вас самих и ваших коллег. Типа, чтобы через полгода, зайдя в свой же код, не думать: «Что это я тут написал?».

Способ 1 Последовательные однострочные комментарии

Первый и, пожалуй, самый «правильный» с точки зрения общепринятых стандартов способ — это использовать кучу обычных однострочных комментариев, которые начинаются с символа ‘#’. Звучит просто, и так оно и есть. Вы просто пишете ‘#’ перед каждой строчкой, которую хотите закомментировать. Это полностью соответствует рекомендациям PEP 8, которые, если коротко, — это такие внутренние правила хорошего тона для Python-кода. Так что, если хотите быть «белым человеком» в мире Python, этот метод — ваш выбор.

Ну, например, представьте, что у вас есть какой-то сложный блок кода, который выполняет кучу действий. Вместо того чтобы писать одну гигантскую простыню, вы можете разбить его на логические части и каждую часть прокомментировать. Как-то так:

# Это первая часть, которая инициализирует переменные
# Мы устанавливаем начальные значения для нашего алгоритма
x = 10
y = 20

# Теперь идет основная логика обработки данных
# Здесь происходит вся магия, не спрашивайте как
result = x + y

# И финальный шаг, вывод результата
# Мы просто печатаем то, что получилось
print(result)

Это выглядит чисто, понятно, и любой, кто знает Python, сразу поймет, где тут что. Более того, современные редакторы кода, вроде VS Code, PyCharm, Sublime Text, делают жизнь еще проще. Вы можете просто выделить несколько строк кода, нажать комбинацию клавиш (чаще всего это Ctrl+/ на Windows или Cmd+/ на Mac), и вуаля — все строки моментально комментируются. То же самое, чтобы их потом быстро раскомментировать. Это реально экономит кучу времени, особенно когда нужно временно отключить кусок кода для отладки.

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

Способ 2 Использование тройных кавычек

Теперь перейдем ко второму способу, который немного хитрее. Это использование строковых литералов, заключенных в тройные одинарные (''' ''') или двойные (""" """) кавычки. В чем тут фишка? Дело в том, что если такой строковый литерал никуда не присвоен (то есть не записан в переменную), то Python-интерпретатор его просто игнорирует. Он его видит, но ничего с ним не делает. Звучит как комментарий, да?

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

"""
Это большой блок текста, который описывает сложную логику.
Мы здесь делаем кое-что очень важное, и нужно это объяснить
как можно подробнее, чтобы никто не забыл.
Представьте, что это целая инструкция по эксплуатации.
"""
def complex_function():
    # ... код функции ...
    pass

'''
А это другой пример, с одинарными тройными кавычками.
Тоже отлично подходит для больших комментариев.
Может быть, вы тут хотите оставить заметку для будущих разработчиков.
'''
class MyClass:
    # ... код класса ...
    pass

Но вот тут есть подводный камень, о котором важно знать. Если вы используете такой тройной строковый литерал в самом начале модуля, функции или класса — Python воспримет это как docstring (документационная строка). Docstrings — это не совсем комментарии в классическом понимании. Это специальные строки, которые используются для документирования кода и могут быть доступны через специальные инструменты. Так что, если вы просто хотите временно отключить код или оставить чисто техническую заметку, а не документацию, лучше так не делать.

Бывает, что из-за этого можно словить SyntaxError. Например, если вы случайно поставите тройные кавычки там, где их не ждали. Или если такой «комментарий» окажется в середине чего-то важного и нарушит структуру. Так что, с этим способом надо быть аккуратнее. По сути, это не совсем комментарий, а скорее «потерянная» строка, которую интерпретатор решил проигнорировать.

Когда какой метод выбрать

Итак, у нас есть два инструмента: последовательные однострочные комментарии с ‘#’ и «потерянные» строки в тройных кавычках. Когда же что лучше использовать? Тут всё просто, если следовать логике.

• Используйте ‘#’ для официальных комментариев: Если вам нужно пояснить какую-то часть кода, дать ей краткое описание, или если вы хотите полностью закомментировать блок, чтобы временно его отключить, — используйте ‘#’. Это чистый, понятный и рекомендуемый PEP 8 способ.
• Используйте тройные кавычки для docstrings и объемных заметок: Если вы пишете документацию к функции, классу или модулю, то тройные кавычки — это ваш выбор (это будут docstrings). Также их можно использовать для каких-то очень длинных заметок, которые не несут информации для API, но помогают разобраться в контексте. Просто помните, что это не совсем комментарий.

Если вам нужно временно отключить кусок кода, который занимает несколько строк — лучше всего выделить его и нажать Ctrl+/ (или Cmd+/). Это намного быстрее и безопаснее, чем пытаться вставить тройные кавычки куда надо. А вот для docstrings, которые как бы встраиваются в структуру вашего кода, тройные кавычки — идеальны.

Главное, чтобы ваш код был читаемым. А комментарии, будь то ‘#’ или тройные кавычки, — это как указатели на дороге, которые помогают не заблудиться в собственном проекте.

Эффективное комментирование кода

Конечно, просто закомментировать код — это только полдела. Важно еще, чтобы комментарии были полезными. Бывает, что пишут такие комментарии, что лучше бы их и не было. Например, «x = x + 1 # увеличиваем x на 1». Ну, это очевидно же! Интерпретатор это и так понимает, и вы понимаете. Комментарии должны объяснять почему вы сделали что-то именно так, а не что делает код. Если код сложный, лучше его переписать, сделать более понятным, чем заваливать его комментариями, которые просто повторяют код.

И вот еще пара моментов:

• Избегайте избыточных комментариев: Не пишите комментарии к каждой строчке. Это только засоряет код.
• Поддерживайте актуальность: Когда вы меняете код, не забывайте менять и комментарии. Иначе они начинают вводить в заблуждение.
• Ясность и краткость: Пишите комментарии четко и по делу.

Есть еще специальные типы комментариев, которые помогают в разработке. Например, TODO, FIXME, HACK, XXX. Это такие метки, которые вы ставите в коде, чтобы вернуться к ним позже. TODO — это что-то, что нужно сделать. FIXME — это указание на то, что здесь есть какая-то ошибка, которую нужно исправить. HACK — это когда вы нашли какое-то временное, не очень элегантное решение, которое работает, но в будущем его надо бы переделать. XXX — это вообще что-то непонятное, какая-то загадка. Такие комментарии помогают в отладке и организации работы над проектом.

В общем, помните: комментарии — это не замена хорошему коду, а его дополнение. Как соус к основному блюду — он улучшает вкус, но не может заменить само блюдо.

Инструменты для упрощения комментирования

А теперь давайте о приятном — как сделать этот процесс комментирования еще проще и быстрее. Современные редакторы кода и IDE — это просто фантастика! Они напичканы функциями, которые реально помогают в повседневной работе. Как я уже говорил, самое главное — это горячие клавиши для комментирования/раскомментирования строк или целых блоков. В VS Code, PyCharm, Sublime Text это делается одной комбинацией. Это реально экономит время, когда вы просто хотите временно выключить какой-то код.

Еще одна крутая фишка — это использование нескольких курсоров. Вы можете поставить несколько курсоров в разных местах документа и начать вводить текст или менять его везде одновременно. Это супер удобно, если вам нужно добавить однотипный комментарий к нескольким строкам, которые расположены далеко друг от друга. Выделяете блок, ставите второй курсор, третий, и потом вводите текст — он появится везде!

Ну и, конечно, возможность сворачивания кода. Когда у вас большой файл с кучей кода и комментариев, вы можете свернуть блок кода или комментарий, чтобы он не мешал, и сосредоточиться на другой части. Это делает навигацию по большому файлу намного удобнее. Так что, если вы еще не освоили все фишки своего редактора кода — самое время начать!