Комментарии в Python: как закомментировать блок кода
В этой статье мы расскажем о комментариях в Python. Разберемся, зачем они нужны и как их использовать.
Когда нужно использовать комментарии в Python
Давайте разберем два самых общих случая использования комментариев в коде. В принципе, это касается не только Python, но и любого другого языка программирования.
Итак, комментарии нужны, чтобы:
- Предотвратить выполнение кода. Иногда вам нужно сделать так, чтобы часть написанного кода не выполнялась. Возможно, она не нужна вам именно в этот момент, но вы планируете использовать ее в дальнейшем. В таком случае эту часть кода можно «закомментировать», т. е. оформить как комментарий.
- Улучшить читаемость. Это очень важно, и не только для нас самих, но и для других разработчиков. При помощи комментариев мы можем объяснить, что делает каждый блок кода. Когда другие разработчики будут читать наш код, благодаря комментариям им будет легко понять, для чего предназначена каждая его часть.
Как (за)комментировать код на Python
В разных языках программирования синтаксис комментариев тоже разный. В Python комментарии начинаются с символа #. Вот пример:
# Код, расположенный ниже, выводит в консоль фразу Hello World! print("Hello World!")
В этом коде я использовал комментарий для пояснения, что делает код. Когда этот код выполняется, интерпретатор игнорирует комментарий и запускает функцию print() .
Мы также можем закомментировать собственно сам код:
# print("Hello World!") print("Happy coding!")
При запуске этого кода будет интерпретироваться только вторая строка.
Комментарии не всегда располагаются над строкой кода, к которой они относятся. Вы можете вставлять их в саму строку:
print("Hello world") # Выводит Hello World
Как делать многострочные комментарии в Python
В отличие от других языков программирования, в Python нет встроенного синтаксиса для создания многострочных комментариев.
К счастью, есть два способа обойти эту проблему. Первый:
# При запуске этого кода # вы видите Hello World! # в консоли. print("Hello world")
Мы можем разделять комментарий на строки, помещая при этом символ # в начале каждой строки.
В следующем примере для размещения комментария мы используем многострочные строки (multi-line strings). Они начинаются и заканчиваются тремя кавычками (сами кавычки могут быть как двойными, так и одинарными).
""" При запуске этого кода вы видите Hello World! в консоли. """ print("Hello World!")
При использовании многострочных строк без присвоения строки в качестве значения переменной эта часть кода игнорируется.
Примечание: важно не забывать об отступах. Если сделаете неправильный отступ перед первым блоком кавычек, получите SyntaxError.
Заключение
Итак, в этой статье мы разобрали, как могут использоваться комментарии в Python, а также рассмотрели их синтаксис. Теперь у вас не должно возникнуть проблем с комментированием кода.
Как закомментировать несколько строк в python
Если следовать стилю кодирования, то PEP-8 рекомендует использовать # и для блочных комментариев . Это значит, что комментировать нужно каждую строку. Например:
# Первая строка комментария # Вторая строка комментария # и т.д. Но существует хак, а именно заключать строковые литералы в тройные апострофы:
''' Первая строка комментария Вторая строка комментария и т.д. ''' Многострочные комментарии в Python
В Python, для однострочных комментариев используется символ # . Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке. Есть ли какая-то возможность использовать многострочные комментарии (аналог /* . */ из Си) в Python? UPD: Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
Отслеживать
Dmitriy Simushev
задан 12 окт 2015 в 11:48
Dmitriy Simushev Dmitriy Simushev
17.9k 5 5 золотых знаков 48 48 серебряных знаков 85 85 бронзовых знаков
Как это сделать в VIM штатными средствами: stackoverflow.com/a/2561497
12 окт 2015 в 19:50
Мой вопрос сводится скорее к «как использовать многострочные комментарии в языке, где нет многострочных комментариев», а не к «как использовать редакторы кода для автоматического создания пачки однострочных комментариев»
13 окт 2015 в 11:16
5 ответов 5
Сортировка: Сброс на вариант по умолчанию
Насколько мне известно, отдельного синтаксиса для многострочных комментариев в Python нет. В тоже время, можно использовать строковые литералы, заключенные в тройные апострофы, например так:
''' Это строковый литерал. Но здесь он используется как многострочный комментарий ''' Строковые литералы, заключенные в тройные кавычки, могут содержать:
- кавычки ( » )
- апострофы ( ‘ )
- docstring комментарии ( «»»func desc»»» )
- переводы строк
В тоже время, стоит помнить, что такой строковый литерал не должен содержать внутри символов »’ . Это требование аналогично запрету на последовательность символов */ внутри многострочного комментария Си.
Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.
В тоже время, как верно отметил @jfs, руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Отслеживать
ответ дан 12 окт 2015 в 11:48
Dmitriy Simushev Dmitriy Simushev
17.9k 5 5 золотых знаков 48 48 серебряных знаков 85 85 бронзовых знаков
Действительно, это способ описан во всех (или почти всех) книгах о Python
12 окт 2015 в 12:11
Руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке.
Один из явных признаков неумелого программирования — это наличие закомментированных фрагментов кода. Используйте систему контроля версий и/или ваше IDE, чтобы временно убрать/закомментировать код при отладке. Настройте ваше окружение, чтобы вы могли это делать не задумываясь, нажимая пару клавиш.
Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.
«»»multiline string literal»»» не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:
>>> def f(): . """abc""" . >>> f.__doc__ 'abc' Попытка использовать «»»»»» в качестве многострочного комментария сломается на первой docstring, даже если бы не было других более подходящий решений для данной задачи.
Многострочные комментарии в Python
Поддерживает ли Python многострочные комментарии так, как это реализовано в других языках? Какие варианты написания блочных комментариев в Python?
В большинстве языков программирования присутствует синтаксис для блочных комментариев, которые охватывают несколько строк текста, например C или Java:
/* Блочный комментарий. Охватывает несколько строк. */ int answer = 42; Есть ли в Python аналогичные многострочные комментарии? Короткий ответ: нет, по крайней мере, не совсем точно так же.
Python использует различные соглашения и синтаксис для блочных комментариев, которые охватывают несколько строк. В этой статье будут показаны некоторые варианты создания многострочных комментариев в Python.
Вариант 1: последовательные однострочные комментарии
Первым вариантом для комментирования нескольких строк кода в Python является простое использование # однострочного комментария для каждой строки:
# Это «блочный комментарий» в Python, сделанный # из нескольких однострочных комментариев. answer = 42 Большинство проектов Python следуют этому стилю, а руководство по стилю написания кода PEP 8 Python также рекомендует использовать повторяющиеся однострочные комментарии. Поэтому в большинстве случаях рекомендуется использовать их. Это также единственный способ написать «реальных» блочных комментариев в Python, которые игнорируется парсером.
Т.к. Python не поддерживает истинные многострочные комментарии, то для того чтобы закомментировать несколько строк кода требуется больше усилий. Приведём ряд полезных советов по ускорения работы с ними. У большинства редакторов кода есть шорткаты для блочных комментариев. Например, в Sublime Text достаточно просто выбирать пару строк, используя shift и клавиши курсора (или мышь), а затем нажимать cmd + /, чтобы закомментировать их все сразу.
Это даже работает в обратном порядке, то есть можно выбрать блок однострочных комментариев, и когда набирается клавиатурный шорткат cmd + /, весь блок снова раскомментируется.
Другие редакторы тоже поддерживают такую возможность: Atom, VS Code и даже Notepad++ имеют встроенные шорткаты для блочного комментирования в Python. Управление комментариями Python вручную – это неблагодарная работа, поэтому такая функция редактора может сэкономить много времени.
Вариант 2: использование многострочных строк вместо комментариев
Ещё одним вариантом для написания «правильных» многострочных комментариев в Python является использование многострочных строк с синтаксисом «»» (три кавычки). Например:
""" Блок комментариев в Python, сделанный из многострочной строковой константы. """ answer = 42 Можно использовать тройные кавычки для создания чего-то, что напоминает многострочный комментарий в Python. Необходимо убедиться, что правильно ввели «»», иначе будет получено исключение SyntaxError. Например, если нужно определить блочный комментарий внутри функции с помощью такого синтаксиса, то должны выполнить это следующим образом:
def add_stuff(a, b): result = a + b """ Теперь возвращается результат. Ещё один пример многострочного комментария. """ return result Имейте в виду, что данный метод не создает «истинных» комментариев. Он просто вставляет текстовую константу, которая ничего не делает. Это то же самое, что вставить правильную однострочную строку где-то в коде и никогда не обращаться к ней.
Тем не менее, такая потерянная строковая константа не будет отображаться в байт-коде, фактически превращая её в многострочный комментарий. Далее доказательство того, что неиспользуемая строка не будет отображаться в дизассемблированном байт-коде CPython:
>>> import dis >>> dis.dis(add_stuff) 2 0 LOAD_FAST 0 (a) 2 LOAD_FAST 1 (b) 4 BINARY_ADD 6 STORE_FAST 2 (result) 8 8 LOAD_FAST 2 (result) 10 RETURN_VALUE Однако будьте осторожны, когда помещаете такие «комментарии» в код. Если строка следует сразу после сигнатуры функции, определения класса или в начале модуля, она превращается в docstring, которая имеет совсем другое значение в Python:
def add_stuff(a, b): """ Это теперь связанная с docstring функция с объектом функции и доступным как метаданные времени выполнения. """ result = a + b return result Docstrings («строки документации») позволяют сопоставлять удобочитаемую документацию с модулями, функциями, классами и методами Python. Они отличаются от комментариев исходного кода.
Комментарий удаляется парсером, тогда как docstring встраивается в байт-код и ассоциируется с документированием объекта. Её можно даже запросить к программному объекту во время выполнения.
Как это было сказано ранее, единственный способ получить «истинные» многострочные комментарии в Python, которые игнорируются парсером, заключается в использовании нескольких комментариев # для каждой однострочной строки.
Но в некоторых случаях использование тройных кавычек, может быть правильным выбором. Старайтесь избежать их использования в готовом к продашену коде.
Выводы
- В отличие от других языков программирования Python не поддерживает многострочные комментарии из коробки.
- Рекомендуемый способ закомментировать несколько строк кода в Python — использовать последовательные # однострочные комментарии. Это единственный способ получить «истинные» комментарии в исходном коде, которые удаляются парсером Python.
- Вы можете использовать строки с тремя кавычками «»», чтобы создать что-то похожее на многострочные комментарии в Python, но это не идеальный метод, и такие могут превратиться в случайные docstrings.