как в питоне закомментировать блок кода
Комментирование кода в Python (Урок №5)
Прежде чем двигаться далее, изучим короткую, но важную тему комментирования кода в Python.
Бывает так, что программист написал программу, отложил ее в сторону на несколько дней, а потом с удивлением понимает, что уже и не помнит, что там нагородил =)
На самом деле, это частая ситуация. Я сам регулярно возвращаюсь к своим старым программам и радуюсь (но не всегда), что комментировал собственный код.
И, как результат, я быстрее понимаю, что сам и написал =)
Что такое комментирование кода?
Если кратко, то это поясняющие записи, к тем или иным командам. Можно провести аналогию с заметками на полях книги.
Но прежде чем продолжить далее, отмечу, что можете посмотреть видео (в нем больше информации, по понятным причинам), или прочитать текстовую версию чуть ниже.
Не забудьте подписаться на мой Youtube-канал.
Как комментировать код в Python?
При этом, интерпретатор Python игнорирует все символы, которые находятся после # и до конца строки.
Обратите внимание, что можно не только оставлять полезные заметки, поясняющие работу программу, но и временно «блокировать» выполнение той или иной команды.
Если мы запустим код выше на выполнение, то получим 8 (результат сложения переменных d = b + c).
Но так как две строки
закомментированы, то они не будут исполняться интерпретатором. И мы не увидим на экране, какие значения у переменных b и c.
Это полезная фича, когда тестируется программа, или ищут ошибки в коде.
Но в финальном варианте программы, разумеется, закомментированные команды лучше удалить, чтобы не засорять код командами, которые не используются при работе программы.
При этом поясняющие комментарии лучше оставить.
Понятно, что не нужно комментировать абсолютно все команды. Но важные моменты, или те, что нельзя сразу понять, лучше пояснить.
Как сразу закомментировать много строк кода?
Бывает так, что нужно сразу закомментировать много строк кода, которые временно нужно исключить. Если вручную ставить в начале каждой строки знак #, то можно быстро разозлиться.
К счастью, большинство редакторов кода позволяют это сделать быстро.
Например, если используете PyCharm, то достаточно выделить нужный блок кода и нажать сочетание клавиш CTRL + /
Если нужно раскомментировать много строк кода, то опять выделяем нужные строки и снова нажимаем сочетание клавиш CTRL + /.
Использование комментариев в Python
В этом руководстве мы обсудим что такое комментарии, зачем они нужны и как правильно записывать многострочные и однострочные комментарии в языке программирования Python.
Введение
По мере того, как ваши программы становятся все длиннее и сложнее, следует добавлять в код заметки, поясняющие подход, используемый вами для решения поставленной задачи.
Комментарии позволяют писать заметки и пояснять код прямо внутри программы.
Комментарии используются там, где код недостаточно понятен сам по себе. По сути, это операторы или строки, игнорируемые интерпретаторами Python.
Снабжая программу комментариями, вы делаете код более читабельным для людей, поскольку это в удобной форме поясняет назначение того или иного блока или строчки кода.
В зависимости от назначения программы, комментарии могут выполнять роль личных заметок или списков задач, которые еще предстоит выполнить, либо их можно писать для других программистов, чтобы тем было проще понять, как работает ваш код.
Открой для себя мир моментальных анонсов новых статей.
Как правило, лучше всего писать комментарии по ходу дела, пока вы пишете или обновляете программу – если вернуться к их написанию позже, вы можете уже не вспомнить ход своих мыслей в тот момент, и в долгосрочной перспективе такие комментарии могут оказаться менее полезными.
Создание комментария
Чтобы написать комментарий, начните строку с символа #. Python проигнорирует все, что будет написано после него. Как правило, комментарии выглядят примерно так:
Комментарии также можно размещать в конце строки:
Многострочные комментарии
В Python нет отдельного синтаксиса для многострочных комментариев. Однако, равноценного результата можно добиться, используя многострочную строку:
Если строка не привязана к какой-либо переменной, Python прочитает ее как код, но в итоге проигнорирует.
Пример использования
Иногда программисты, работающие с Python, ставят символ # перед строчкой кода, чтобы временно удалить ее из программы на время проверки. Этот прием называется «закомментировать код» и пригождается в тех случаях, когда вы пытаетесь выяснить, почему программа не работает. Закончив проверки, вы можете быстро вернуть код обратно, просто удалив поставленный перед строчкой символ #.
Заключение
Писать комментарии в коде Python – очень полезная привычка, и даже если на данный момент вы не видите в этом необходимости, то поверьте: пояснения к работе различных участков кода могут понадобиться как программистам, его читающим, так и лично вам, если вы вернетесь к работе над программой после долгого перерыва.
Это особенно полезно в том случае, если ваш код является открытым или выложен на GitHub, где другие программисты пытаются его дополнить. Подробно ознакомив их с тем, что вы уже успели сделать, вы поможете им быстрее освоиться и начать работу.
Комментирование Python кода
Программирование отражает ваш образ мышления, чтобы описать отдельные шаги, которые вы предприняли для решения проблемы с помощью компьютера. Комментирование вашего кода помогает объяснить ваш мыслительный процесс, а также помогает вам и другим людям понять смысл вашего кода. Это позволяет вам легче находить ошибки, исправлять их, впоследствии улучшать код, а также повторно использовать его и в других приложениях.
Комментирование важно для всех видов проектов, независимо от того, маленькие они, средние или довольно большие. Это важная часть вашего рабочего процесса, и считается хорошей практикой для разработчиков. Без комментариев все может запутаться, очень быстро. В этой статье мы расскажем о различных методах комментирования, поддерживаемых Python, и о том, как его можно использовать для автоматического создания документации для вашего кода с использованием так называемых строк документации уровня модуля.
Хорошие против плохих комментариев
Как бы ни были важны комментарии, все еще можно писать плохие комментарии. Они всегда должны быть короткими, прямолинейными и добавлять информативную ценность.
Например, это довольно бесполезный комментарий:
Следующий пример демонстрирует более полезный комментарий и дает переменным очевидные имена:
Типы комментариев
В следующих разделах я опишу каждый тип комментария.
Однострочные комментарии
Такой комментарий начинается с хеш-символа ( # ) и сопровождается текстом, который содержит дополнительные пояснения.
Вы также можете написать комментарий рядом с оператором кода. Следующий пример показывает, это:
Руководство по стилю для кода Python ( PEP8 ) рекомендует менее 79 символов на строку. На практике 70 или 72 символа в строке легче читать, и поэтому рекомендуется. Если ваш комментарий приближается к этой длине или превышает ее, тогда вы захотите распределить его по нескольким строкам.
Многострочные комментарии
Как уже упоминалось выше, весь блок комментариев также понимается Python. Эти комментарии служат встроенной документацией для других, читающих ваш код, и обычно объясняют вещи более подробно
Технически Python не имеет явной поддержки многострочных комментариев, поэтому некоторые варианты считаются обходным решением, но все же работают для многострочных комментариев.
Версия 1 объединяет однострочные комментарии следующим образом:
Версия 2 проще, чем версия 1. Изначально она предназначалась для создания документации (подробнее об этом ниже), но ее также можно использовать для многострочных комментариев.
Обратите внимание, что последняя версия должна быть заключена в специальные кавычки ( «»» ) для работы, а не хеш-символы.
Обычная практика
Довольно часто начинать Python-файл с нескольких строк комментариев. В этих строках указывается информация о проекте, назначении файла, программисте, который его разработал или работал над ним, и лицензии на программное обеспечение, которое используется для кода.
Этот фрагмент взят из одного из примеров, которые я использую в учебных целях. Комментарий начинается с описания, за ним следует уведомление об авторских правах с моим именем и год публикации кода. Ниже вы увидите, что код лицензирован под GNU Public License ( GPL ). Для того, чтобы связаться со мной, мой адрес электронной почты также добавлен туда.
Комментарии документации
Python имеет встроенную концепцию под названием «строки документации», которая является отличным способом связать написанную вами документацию с модулями, функциями, классами и методами Python. Строка документа добавляется в качестве комментария прямо под заголовком функции, модуля или объекта и описывает действия функции, модуля или объекта. Ожидается, что будут следовать этим правилам:
Начните строку документа с заглавной буквы и завершите ее точкой.
Это основной пример того, как это выглядит:
Существует ряд инструментов, которые автоматически генерируют документацию из строк документации, таких как Doxygen, PyDoc, pdoc и расширение autodoc для Sphinx. Мы объясним вам, как работать с ними в следующей статье.
Заключение
Написание правильных комментариев в вашем коде Python не так сложно, и вам просто нужна сила выносливости. Это помогает всем, кто пытается понять ваш код, включая вас самих, когда вы в следующий раз вернетесь к нему. Мы надеемся, что совет, который мы дали вам здесь, облегчит вам создание более качественных комментариев и документации в вашем коде.
№28 Как писать комментарии / для начинающих
Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.
Куда лучше добавлять комментарии при создании или обновлении программы, иначе можно утратить контекст. Комментарии, добавленные позже, могут быть далеко не настолько эффективными.
Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.
Однострочные комментарии в Python
Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).
При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
Многострочные комментарии в Python
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
С помощью символа #
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
Docstring в Python
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
Как задать docstring в Python?
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
В чем отличие между комментарием и docstring?
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
Многострочные комментарии в Python
Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
5 ответов 5
Насколько мне известно, отдельного синтаксиса для многострочных комментариев в Python нет. В тоже время, можно использовать строковые литералы, заключенные в тройные апострофы, например так:
Строковые литералы, заключенные в тройные кавычки, могут содержать:
Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.
В тоже время, как верно отметил @jfs, руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке.
Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.
«»»multiline string literal»»» не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:
Попытка использовать «»»»»» в качестве многострочного комментария сломается на первой docstring, даже если бы не было других более подходящий решений для данной задачи.