Комментирование кода — хорошая практика, если вы хотите помочь другим людям понять то, что вы написали. Очень важно уметь комментировать в Python, если вы работаете в большой команде.
Также, это очень важно, если вы хотите понять в будущем, что вы написали. Возврат к старому коду может дезориентировать, и это проблема, если надеетесь постоянно поддерживать приложение.
Также читайте: Что такое Python и зачем его изучать?
В этом посте мы рассмотрим, как комментировать в Python и как комментировать логично и полезно.
Как комментировать в Python и сделать это полезным
Хорошая новость в том, что в Python очень легко комментировать. Вам просто нужно добавить хэштег к тому, что вы собираетесь вводить:
Таким образом, все, что вы написали, будет проигнорировано интерпретатором и будет выделено для всех, кто просматривает ваш код. Вы можете разместить комментарий Python либо в отдельной строке, либо даже в строке с кодом, который хотите объяснить.
Тогда научиться комментировать в Python легко; самое сложное — знать, когда комментировать и как обеспечить разборчивость и полезность комментариев.
Также читайте: Python или Java: какой язык лучше изучать и в чем различия?
Один из способов добиться этого — убедиться, что ваши комментарии соответствуют основным передовым практикам. Согласно Руководству по стилю для кода Python, вы должны стремиться к тому, чтобы ваши комментарии не превышали 79 символов в строке. Это избавляет читателя от необходимости прокручивать по горизонтали и сохраняет все аккуратно.
Хотя встроенные комментарии могут быть полезны, обратите внимание, что размещение их последовательно может затруднить понимание того, что код, а что нет, это значительно затрудняет интерпретацию программы с первого взгляда.
Это сбивает с толку, например:
Гораздо лучший способ добиться чего-то подобного:
Но, конечно, любой из них был бы примером ненужного комментария!
Когда и как комментировать в Python
Что касается того, что нужно комментировать…
Вот некоторые общие и полезные подписи, которые можно добавить в код:
- Немного о любой новой функции и о том, что она делает
- Объяснение того, для чего предназначена переменная или набор переменных
- Объяснение того, почему вы что-то сделали определенным образом (если это не очевидно)
- Выделение ключевых и важных частей вашего кода
- Предоставление предупреждений
Несколько полезных советов, как сделать комментарии полезными, а не отвлекать их:
- Делайте комментарии краткими и не длиннее, чем необходимо — уважайте время своего читателя!
- Избегайте комментариев, в которых говорится об очевидном; не слишком комментируй
- Не просто объясняйте, что ч делает: объясните, почему вы поместили это туда и почему это важно
- Будьте вежливы и дружелюбны! Ни в коем случае не используйте комментарии, чтобы пристыдить других программистов. Это быстрый способ стать наименее популярным человеком в вашей команде.
Другие варианты использования комментариев Python
Основное использование комментариев в Python — предоставление полезных советов и инструкций. Что может помочь другим ориентироваться в коде. Тем не менее, есть и другие сценарии, в которых использование кода будет полезным.
Также читайте: Я хочу разрабатывать приложения для Android — какие языки мне следует изучать?
Комментарии в заголовке, например, находятся вверху файла и объясняют, что делает код под ним. Они могут даже включать некоторые полезные указания, которые помогут читателю найти важные функции.
Комментарии в заголовке можно использовать как место для вставки уведомления об авторских правах или для объявления авторства кода. Некоторым людям нравится использовать чрезмерный ASCII для придания своему коду ярких названий.
Еще одно использование комментариев Python — помочь быстро сориентироваться в коде с помощью инструмента поиска. Я часто оставляю себе комментарии, чтобы быстро переключаться между разными точками кода или чтобы отметить то, что мне нужно сделать позже. Если я оставляю что-то незаконченным, я буду комментировать это, чтобы потом легко найти.
Наконец, вы можете использовать комментарии в Python, чтобы шутить. Это раздражает некоторых людей и, конечно же, не сделает код чистым и эффективным. Но лично? Я считаю, что программирование одиночная работа, и иногда нахождение немного остроумия или «привет» могут поднять настроение.
Быть крутым ничего не стоит!
Заключение
Имейте в виду, что знание того, как комментировать в Python, не освобождает вас от необходимости писать чистый, читаемый код. Ваши комментарии должны служить полезным дополнительным руководством для читателей, а не розеттским камнем для расшифровки вашего бреда!
Это означает, что вам следует:
- Структурируйте свой код логически
- Используйте умные названия для переменных и функций, а также согласованные соглашения об именах
- Правильное использование новых строк и отступов (к счастью, Python заставляет нас делать последнее)
Есть те, кто считает, что комментирование указывает на то, что код изначально был написан плохо. Есть разработчики, которые вообще проповедует не использовать комментарии!
В конечном счете, насколько скупо или обильно вы решите комментировать свой код, зависит от личных предпочтений. Но имейте в виду, что кто-то, просматривающий ваш код, может быть не таким опытным, как вы, и небольшое руководство окажеться большим подспорьем! Основная цель — сделать так, чтобы любой, кому нужно понимать ваш код, смог, и пока это так, решать вам, как вы это сделаете!
Так вот как комментировать в Python. Что вы считаете полезным/раздражающим при чтении кода? Что-то мы пропустили? Дайте нам знать в комментариях ниже!
Если вы хотите узнать больше о кодировании Python, мы рекомендуем попробовать онлайн-курс. Это лучший способ быстро освоить новый язык программирования.
