Как комментировать в Python – Советы и лучшие практики

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

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

Также читайте: Как использовать строки в Python

В этом посте мы рассмотрим, как комментировать в Python и как комментировать логично и полезно.

Как комментировать в Python и сделать его полезным

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

#This is a comment!

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

Тогда научиться комментировать в Python просто; сложность заключается в том, чтобы знать, когда комментировать и как сделать эти комментарии разборчивыми и полезными.

Также читайте: Как печатать на Python

Один из способов сделать это – убедиться, что ваши комментарии соответствуют основным рекомендациям. Согласно Руководству по стилю для кода Python, вы должны стремиться к тому, чтобы ваши комментарии были ниже 79 символов в строке. Это избавляет читателя от необходимости прокрутки по горизонтали и сохраняет все аккуратно.

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

Это сбивает с толку, например:

Намного лучший способ достигнуть чего-то подобного был бы:

#If the baddy overlaps the mine, then the baddy is sent off page and the graphics 

Но, конечно, любой из них будет примером ненужного комментирования!

Когда и как комментировать в Python

Что касается того, что нужно комментировать …

Некоторые общие и полезные заголовки, которые нужно добавить в ваш код:

• Немного о любой новой функции и о том, что она делает
• Объяснение того, для чего переменная или набор переменных
• Объяснение, почему вы сделали что-то определенным образом (если это не очевидно)
• Выделение ключевых и важных частей вашего кода
• Предоставление предупреждений

Несколько полезных советов о том, как оставить комментарии полезными, а не отвлекающими:

• Оставляйте комментарии краткими и не дольше, чем необходимо – уважайте время своего читателя!
• Избегайте комментариев, которые утверждают очевидное; не более  комментариев
• Не просто объясните, что что- то делает: объясните, почему вы это делаете и почему это важно
• Будьте вежливы и дружелюбны! Абсолютно не используйте комментарии, чтобы опозорить других кодеров. Это быстрый способ стать наименее популярным человеком в вашей команде.

Больше применений для комментариев Python

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

Также читайте: Как создать файл в Python и многое другое

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

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

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

Наконец, вы можете использовать комментарии в Python, чтобы шутить. Это будет раздражать некоторых людей и, конечно, не сделает ваш код максимально чистым и эффективным. А лично? Я считаю, что программирование может быть одинокой работой, и иногда нахождение немного остроумия или «привет» может поднять настроение.

Быть хорошим не стоит ничего!

Заключительные мысли

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

Это означает, что вы также должны:

• Структурируйте свой код в логической манере
• Используйте умные имена для переменных и функций вместе с согласованным соглашением об именах
• Правильное использование новых строк и отступов (к счастью, Python заставляет нас делать последнее)

Есть те, кто считает, что комментирующий код на самом деле является признаком того, что код был написан плохо с самого начала. Эта толпа на самом деле проповедует против использования комментариев в целом!

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

Вот как комментировать в Python. Что вы находите полезным / раздражающим при чтении кода? Мы что-то пропустили? Дайте нам знать в комментариях ниже!

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

Источник записи: https://www.androidauthority.com