Как сделать комментарий в питоне

Обновлено: 07.07.2024

Комментарии, которые противоречат коду, хуже, чем отсутствие комментариев. Всегда делайте приоритет обновления комментариев при изменении кода!

Комментарии должны быть полными предложениями. Первое слово должно быть написано заглавными, если только это не идентификатор, который начинается со строчной буквы (никогда не меняйте регистр идентификаторов!).

Блочные комментарии обычно состоят из одного или нескольких абзацев, построенных из полных предложений, причем каждое предложение заканчивается точкой.

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

При написании английского, следуйте Strunk и White.

Python программисты из стран, не говорящих по-английски: пишите свои комментарии на английском языке, если уверены на 120%, что код никогда не будет прочитан людьми, которые говорят на вашем языке.

Блок комментариев:

Встроенные комментарии:

Используйте встроенные комментарии экономно.

Встроенные комментарии не нужны и фактически отвлекают, если они утверждают очевидное. Не делай этого:

Но иногда полезно:

Строки документации:

Условные обозначения для написания хорошей документации описаны в PEP 257.

Пишите строки документации для всех общедоступных модулей, функций, классов и методов. Строки документации не нужны для закрытых методов, но у вас должен быть комментарий, описывающий, что делает метод. Этот комментарий должен появиться после строки def .

В PEP 257 описаны хорошие соглашения о документах. Обратите внимание, что наиболее важно, что """ , заканчивающий многострочную строку документации, должно быть на отдельной строке:

Для строк документации в одну строку, пожалуйста, сохраняйте закрывающий символ """ на этой же строке.

Поддерживает ли Python многострочные комментарии так, как это реализовано в других языках? Какие варианты написания блочных комментариев в Python?

В большинстве языков программирования присутствует синтаксис для блочных комментариев, которые охватывают несколько строк текста, например C или Java:

Есть ли в Python аналогичные многострочные комментарии? Короткий ответ: нет, по крайней мере, не совсем точно так же.

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

Вариант 1: последовательные однострочные комментарии

Т.к. Python не поддерживает истинные многострочные комментарии, то для того чтобы закомментировать несколько строк кода требуется больше усилий. Приведём ряд полезных советов по ускорения работы с ними. У большинства редакторов кода есть шорткаты для блочных комментариев. Например, в Sublime Text достаточно просто выбирать пару строк, используя shift и клавиши курсора (или мышь), а затем нажимать cmd + /, чтобы закомментировать их все сразу.

Это даже работает в обратном порядке, то есть можно выбрать блок однострочных комментариев, и когда набирается клавиатурный шорткат cmd + /, весь блок снова раскомментируется.

Другие редакторы тоже поддерживают такую возможность: Atom, VS Code и даже Notepad++ имеют встроенные шорткаты для блочного комментирования в Python. Управление комментариями Python вручную – это неблагодарная работа, поэтому такая функция редактора может сэкономить много времени.

Вариант 2: использование многострочных строк вместо комментариев

Тем не менее, такая потерянная строковая константа не будет отображаться в байт-коде, фактически превращая её в многострочный комментарий. Далее доказательство того, что неиспользуемая строка не будет отображаться в дизассемблированном байт-коде CPython:

Комментарий удаляется парсером, тогда как docstring встраивается в байт-код и ассоциируется с документированием объекта. Её можно даже запросить к программному объекту во время выполнения.

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

В этом руководстве мы узнаем о комментариях и утверждениях Python. Мы поговорим о том, что такое комментарии, о различных типах и о том, как их можно определить.

Что такое комментарии в Python?

Эти комментарии – операторы, которые не являются частью программы. По этой причине операторы комментариев пропускаются при выполнении программы.

Обычно мы используем комментарии для кратких заметок о фрагменте кода. Также важны комментарии, чтобы другие могли легко понять программу. С другой стороны, комментарии полезны и самому программисту. Понять программу, сделанную давно, можно просто по комментариям к программе.

Различные типы комментариев

В Python есть два типа комментариев: однострочные и многострочные. Однострочный обычно используется для краткого и быстрого комментария (или для отладки программы, мы увидим это позже). С другой стороны, мы используем комментарии из нескольких строк, чтобы записать что-то гораздо более подробно или заблокировать весь фрагмент кода.

1. Однострочные

2. Многострочные

Комментарии, состоящие из нескольких строк, немного отличаются. Просто используйте 3 одинарные кавычки до и после части, которую вы хотите прокомментировать.

Что такое заявления Python?

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

Есть ли какая-то возможность использовать многострочные комментарии (аналог /* . */ из Си) в Python?

UPD:

Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.

Мой вопрос сводится скорее к "как использовать многострочные комментарии в языке, где нет многострочных комментариев", а не к "как использовать редакторы кода для автоматического создания пачки однострочных комментариев"

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

Строковые литералы, заключенные в тройные кавычки, могут содержать:

кавычки ( " )
апострофы ( ' )
docstring комментарии ( """func desc""" )
переводы строк

В тоже время, стоит помнить, что такой строковый литерал не должен содержать внутри символов ''' . Это требование аналогично запрету на последовательность символов */ внутри многострочного комментария Си.

Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.

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

Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.

Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.

"""multiline string literal""" не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:

Попытка использовать """""" в качестве многострочного комментария сломается на первой docstring, даже если бы не было других более подходящий решений для данной задачи.

Добавить в избранное

П ри написании кода на Python всегда полезно делать код легко читаемым. Организация кода, присвоение переменным и функциям описательных имен – это несколько способов сделать это.

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

Добавление комментариев к вашему коду Python сэкономит вам много времени и усилий, если вы посмотрите на свой код в будущем. Допустим, вы хотите изменить сценарий, который вы написали несколько месяцев или лет назад. Скорее всего, вы не помните, почему вы написали какой-то сложный кусок кода, если вы не добавили комментарий. Комментарии также помогают другим разработчикам понять ваш код и его назначение.

Комментарии должны быть краткими и точными. Не объясняйте что-то очевидное для читателя.

В этой статье рассматриваются основы написания комментариев на Python.

Написание комментариев в Python

Комментарии могут быть добавлены в начале строки или встроены в другой код:

Пробел после хеш-метки не обязателен, но он улучшит читабельность комментария.

Символ хеша внутри строкового литерала не указывает на начало строки комментария. Это просто хэш-символ:

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

Комментарии также полезны при отладке скрипта. Вместо удаления некоторых строк или блоков, вы можете закомментировать их:

Многострочные комментарии в Python (блоки комментариев)

В отличие от других популярных языков программирования, Python поддерживает только однострочные комментарии.

Самый простой способ написать многострочные комментарии в Python – добавить однострочные комментарии один за другим:

Другой вариант – использовать строки документации.

Строки документации – это многострочные строковые литералы, которые используются для документирования того, что делает модуль, функция, класс или метод.

Строка документа начинается и заканчивается тройными двойными кавычками ( “””) и может занимать одну или несколько строк:

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

Python

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

Поскольку строка shebang начинается с символа хеша, она рассматривается как комментарий и автоматически игнорируется интерпретатором Python.

Вывод

Если у вас есть какие-либо вопросы или отзывы, не стесняйтесь оставлять комментарии.

Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

Читайте также: