Комментарии в коде языка Python
Комментарии, которые противоречат коду, хуже, чем отсутствие комментариев. Всегда делайте приоритет обновления комментариев при изменении кода!
Комментарии должны быть полными предложениями. Первое слово должно быть написано заглавными, если только это не идентификатор, который начинается со строчной буквы (никогда не меняйте регистр идентификаторов!).
Блочные комментарии обычно состоят из одного или нескольких абзацев, построенных из полных предложений, причем каждое предложение заканчивается точкой.
Вы должны использовать два пробела после окончания каждого предложения в комментариях из нескольких предложений, за исключением последнего предложения.
При написании английского, следуйте Strunk и White.
Python программисты из стран, не говорящих по-английски: пишите свои комментарии на английском языке, если уверены на 120%, что код никогда не будет прочитан людьми, которые говорят на вашем языке.
Блок комментариев:
Блочные комментарии обычно применяются к некоторому (или всему) коду, который следует за ними, и имеют отступ на том же уровне, что и комментируемый код. Каждая строка комментария блока начинается с # и одного пробела (если только внутри комментария нет отступа).
Абзацы внутри комментария блока разделяются строкой, содержащей один # .
Встроенные комментарии:
Используйте встроенные комментарии экономно.
Встроенный комментарий — это комментарий в той же строке, что и оператор. Встроенные комментарии должны быть отделены как минимум двумя пробелами от оператора. Они должны начинаться с # и одного пробела.
Встроенные комментарии не нужны и фактически отвлекают, если они утверждают очевидное. Не делай этого:
x = x + 1 # увеличение x
Но иногда полезно:
x = x + 1 # Компенсация границы
Строки документации:
Условные обозначения для написания хорошей документации описаны в PEP 257.
- Пишите строки документации для всех общедоступных модулей, функций, классов и методов. Строки документации не нужны для закрытых методов, но у вас должен быть комментарий, описывающий, что делает метод. Этот комментарий должен появиться после строки def .
- В PEP 257 описаны хорошие соглашения о документах. Обратите внимание, что наиболее важно, что «»» , заканчивающий многострочную строку документации, должно быть на отдельной строке:
"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """
- ОБЗОРНАЯ СТРАНИЦА РАЗДЕЛА
- Разметка кода Python, PEP 8
- Пробелы в выражениях и операторах языка Python
- Когда использовать запятые в коде на Python
- Комментарии в коде языка Python
- Соглашения об именах
- Рекомендации по программированию на Python
Как в python закомментировать часть строки?
В CSharp это делается как
/* text */
Странно, но ничего в гугле я не нашёл.
- Вопрос задан более двух лет назад
- 228 просмотров
Комментировать
Решения вопроса 0
Ответы на вопрос 1
Ответ написан более двух лет назад
Комментировать
Нравится Комментировать
Ваш ответ на вопрос
Войдите, чтобы написать ответ
- Python
Палиндромы leetcode, в VS все правильно, на сайте другой ответ, что делать?
- 1 подписчик
- 3 часа назад
- 58 просмотров
- HTML
- +3 ещё
Почему не работает переход на страницу?
- 1 подписчик
- 4 часа назад
- 87 просмотров
- Python
- +1 ещё
Реально ли вывести виджет с какой-либо инфой поверх PySide6.QtMultimediaWidgets.QVideoWidget?
- 1 подписчик
- 4 часа назад
- 13 просмотров
- Python
Почему не проходит код для решения задачи на leetcode?
- 1 подписчик
- 5 часов назад
- 74 просмотра
- Python
Почему текстовый редактор и консоль по-разному присваивают ссылки на переменные Python?
- 1 подписчик
- 5 часов назад
- 32 просмотра
- Python
- +1 ещё
Почему callback_query_handler не видит call.data?
- 1 подписчик
- 9 часов назад
- 41 просмотр
- Python
При выводе users_cards выводится [, . ] как это исправить?
- 1 подписчик
- 11 часов назад
- 34 просмотра
- Python
В приложении django 4.2 + django rest framework: Model.__str__ нужен только для админки?
- 1 подписчик
- 13 часов назад
- 47 просмотров
- Python
- +1 ещё
Не правильная проверка ячейки таблицы через цикл, почему не записывается переменная?
- 1 подписчик
- 13 часов назад
- 38 просмотров
- Python
Почему падает бот?
- 1 подписчик
- вчера
- 85 просмотров
от 120 000 ₽
от 120 000 до 240 000 ₽
ATI.SU • Санкт-Петербург
от 170 000 до 260 000 ₽
20 нояб. 2023, в 00:43
20000 руб./за проект
20 нояб. 2023, в 00:35
3500 руб./за проект
19 нояб. 2023, в 23:12
55555 руб./за проект
Минуточку внимания
Присоединяйтесь к сообществу, чтобы узнавать новое и делиться знаниями
- Не могу настроить почтовый сервер(Postfix/Dovecot с интеграцией в MS Active Directory) на alt linux. Может у кого-то есть решение?
- 3 подписчика
- 1 ответ
- 3 подписчика
- 2 ответа
- 2 подписчика
- 1 ответ
- 2 подписчика
- 1 ответ
- 3 подписчика
- 2 ответа
- 2 подписчика
- 2 ответа
- 2 подписчика
- 1 ответ
- 2 подписчика
- 3 ответа
- 2 подписчика
- 1 ответ
- 2 подписчика
- 1 ответ
Евгений Степанищев
Пишу, по большей части, про историю, свою жизнь и немного про программирование. Живу в Казани.
Комментарии в Python
Меня очень раздражает, что в Пайтоне нет многострочных комментариев. И не говорите, что комментарии можно сделать тройными кавычками (или апострофами), это неудобно. Во-первых, тройные кавычки — не комментарий, а многосточная строка (это ремарка для тех, кто не знает Пайтон), поэтому начинать её приходится на том же уровне, что и текущий код.
Во-вторых, попробуйте в большом списке (list) закомментривать большой кусок. Тройные кавычки тут не подойдут:
mylist = [\ 'раз', 'два', """'три', 'четыре',""" 'пять' ]Всем очевидно почему не подойдут? Я не понимаю почему до сих пор в языке нет многострочных комментариев.
Как комментировать в Python — советы и практика
В этом посте объясняется, как комментировать в Python, и приведены рекомендации, которые помогут вам сделать это правильно! Помогите другим понять ваш код.
Менее 1 мин. |
Комментирование кода — хорошая практика, если вы хотите помочь другим людям понять то, что вы написали. Очень важно уметь комментировать в Python, если вы работаете в большой команде.
Также, это очень важно, если вы хотите понять в будущем, что вы написали. Возврат к старому коду может дезориентировать, и это проблема, если надеетесь постоянно поддерживать приложение.
В этом посте мы рассмотрим, как комментировать в Python и как комментировать логично и полезно.
Как комментировать в Python и сделать это полезным
Хорошая новость в том, что в Python очень легко комментировать. Вам просто нужно добавить хэштег к тому, что вы собираетесь вводить:
Таким образом, все, что вы написали, будет проигнорировано интерпретатором и будет выделено для всех, кто просматривает ваш код. Вы можете разместить комментарий Python либо в отдельной строке, либо даже в строке с кодом, который хотите объяснить.
Тогда научиться комментировать в Python легко; самое сложное — знать, когда комментировать и как обеспечить разборчивость и полезность комментариев.
Один из способов добиться этого — убедиться, что ваши комментарии соответствуют основным передовым практикам. Согласно Руководству по стилю для кода Python, вы должны стремиться к тому, чтобы ваши комментарии не превышали 79 символов в строке. Это избавляет читателя от необходимости прокручивать по горизонтали и сохраняет все аккуратно.
Хотя встроенные комментарии могут быть полезны, обратите внимание, что размещение их последовательно может затруднить понимание того, что код, а что нет, это значительно затрудняет интерпретацию программы с первого взгляда.
Это сбивает с толку, например:
Гораздо лучший способ добиться чего-то подобного:
Но, конечно, любой из них был бы примером ненужного комментария!
Когда и как комментировать в Python
Что касается того, что нужно комментировать…
Вот некоторые общие и полезные подписи, которые можно добавить в код:
- Немного о любой новой функции и о том, что она делает
- Объяснение того, для чего предназначена переменная или набор переменных
- Объяснение того, почему вы что-то сделали определенным образом (если это не очевидно)
- Выделение ключевых и важных частей вашего кода
- Предоставление предупреждений
Несколько полезных советов, как сделать комментарии полезными, а не отвлекать их:
- Делайте комментарии краткими и не длиннее, чем необходимо — уважайте время своего читателя!
- Избегайте комментариев, в которых говорится об очевидном; не слишком комментируй
- Не просто объясняйте, что ч делает: объясните, почему вы поместили это туда и почему это важно
- Будьте вежливы и дружелюбны! Ни в коем случае не используйте комментарии, чтобы пристыдить других программистов. Это быстрый способ стать наименее популярным человеком в вашей команде.
Другие варианты использования комментариев Python
Основное использование комментариев в Python — предоставление полезных советов и инструкций. Что может помочь другим ориентироваться в коде. Тем не менее, есть и другие сценарии, в которых использование кода будет полезным.
Комментарии в заголовке, например, находятся вверху файла и объясняют, что делает код под ним. Они могут даже включать некоторые полезные указания, которые помогут читателю найти важные функции.
Комментарии в заголовке можно использовать как место для вставки уведомления об авторских правах или для объявления авторства кода. Некоторым людям нравится использовать чрезмерный ASCII для придания своему коду ярких названий.
Еще одно использование комментариев Python — помочь быстро сориентироваться в коде с помощью инструмента поиска. Я часто оставляю себе комментарии, чтобы быстро переключаться между разными точками кода или чтобы отметить то, что мне нужно сделать позже. Если я оставляю что-то незаконченным, я буду комментировать это, чтобы потом легко найти.
Наконец, вы можете использовать комментарии в Python, чтобы шутить. Это раздражает некоторых людей и, конечно же, не сделает код чистым и эффективным. Но лично? Я считаю, что программирование одиночная работа, и иногда нахождение немного остроумия или «привет» могут поднять настроение.
Быть крутым ничего не стоит!
Заключение
Имейте в виду, что знание того, как комментировать в Python, не освобождает вас от необходимости писать чистый, читаемый код. Ваши комментарии должны служить полезным дополнительным руководством для читателей, а не розеттским камнем для расшифровки вашего бреда!
Это означает, что вам следует:
- Структурируйте свой код логически
- Используйте умные названия для переменных и функций, а также согласованные соглашения об именах
- Правильное использование новых строк и отступов (к счастью, Python заставляет нас делать последнее)
Есть те, кто считает, что комментирование указывает на то, что код изначально был написан плохо. Есть разработчики, которые вообще проповедует не использовать комментарии!
В конечном счете, насколько скупо или обильно вы решите комментировать свой код, зависит от личных предпочтений. Но имейте в виду, что кто-то, просматривающий ваш код, может быть не таким опытным, как вы, и небольшое руководство окажеться большим подспорьем! Основная цель — сделать так, чтобы любой, кому нужно понимать ваш код, смог, и пока это так, решать вам, как вы это сделаете!
Так вот как комментировать в Python. Что вы считаете полезным/раздражающим при чтении кода? Что-то мы пропустили? Дайте нам знать в комментариях ниже!
Если вы хотите узнать больше о кодировании Python, мы рекомендуем попробовать онлайн-курс. Это лучший способ быстро освоить новый язык программирования.