Комментарии в Python
Комментарии в Python

Комментарии в Python

Комментарии – это пояснения к исходному тексту программы. Это может быть описание работы какого-то класса, функции или, например, значение переменной.

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

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

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

Комментарии – это отличный способ быстро вспомнить свой код, написанный ранее.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Комментарии в коде можно сворачивать
Комментарии в коде можно сворачивать
Комментарии в коде можно сворачивать

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

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

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

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

😭
😕
😃
😍