Однострочные и многострочные комментарии в Python

Содержание

Однострочные комментарии
Многострочные комментарии
Шорткаты для комментариев

Несколько курсоров
Свернуть комментарий
Быстрое комментирование строк кода

Чтобы ваш код был легко читаемым другими людьми, нужно придумывать очевидные имена, правильно подбирать названия функциям и правильно организовывать свой код. А комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим.

Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки. Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.

Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.

Хороший комментарии должны быть:

Уместными — не стоит указывать в комментариях очевидные вещи. К примеру, если вы назвали функцию print_black_list(), не нужно писать к ней комментарий # печать черного списка.
Содержательными — должны четко описывать проблему, не должно возникнуть никаких запинок по поводу их понимания.
Короткими — не нужно писать сочинение в комментариях.
Актуальными — одна из проблем комментариев это их сопровождение. Код меняется, а обновлять комментарии часто забывают. Чем старше ваш комментарий, тем больше вероятность, что он лжет.

Плохой комментарий описывает код, отвечая на вопрос "что делает код?". Хороший комментарий отвечает на вопрос "зачем этот код?".

О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина "Чистый код", в главе 4 "Комментарии".

PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.

О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.

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

Чтобы написать однострочный комментарий в Python, достаточно поставить "#" перед комментарием:

# Это однострочный комментарий

print("python")  # Это тоже однострочный комментарий

Python будет считать комментарием все, что находится после "#" и до конца строки.

Многострочные комментарии

Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.

Вариант #1 — писать однострочные комментарии друг за другом:

def multiline_comment_example():
    # Это многострочный комментарий, оформленный
    # в виде однострочных комментариев, следующих
    # друг за другом

Вариант #2 — заключить комментарий в тройные кавычки:

"""
Это многострочный комментарий, 
созданный с помощью
тройных кавычек
"""

Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.

На самом деле это строка, которая не назначена какой-либо переменной. Эта строка не вызывается и ни на что не ссылается, поэтому может быть использована как многострочный комментарий.
Если разместить такой комментарий сразу после определения функции или метода, Python будет считать его фрагментом документации, связанного с данной функцией/методом.

Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.

Подробнее о документировании кода в Python:

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

Шорткаты для комментариев

Процесс комментирования строк можно ускорить, используя шорткаты.

Несколько курсоров

Сразу несколько комментариев можно написать выбрав сразу несколько строк. Для разных редакторов они разные: Ctrl + Left mouse click или Alt + Left mouse click (Cmd + Left mouse click для Mac OS).

В редакторе можно писать комментарий сразу к нескольким строкам.

Свернуть комментарий

В некоторых редакторах (например PyCharm) можно свернуть комментарий, если он стал занимать слишком много места на экране.

Быстрое комментирование строк кода

Часто бывают ситуации, когда нужно закомментировать фрагмент кода (1 строку или сразу несколько строк подряд). Для этого просто выберите нужный фрагмент кода и нажмите Ctrl + / (Cmd + / для Mac OS)

Быстро закомментировать строки – Ctrl + / или Cmd + /

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