Использование Python comment в программировании
[
Написание комментариев в Python (Руководство)
Еще один замечательный и простой способ увеличить читаемость вашего кода - использование комментариев!
В этом руководстве вы ознакомитесь с основами написания комментариев на Python. Вы узнаете, как писать комментарии, которые являются чистыми и лаконичными, и когда вам может не понадобиться писать комментарии вообще.
Вы также узнаете:
- Почему комментирование вашего кода так важно
- Лучшие практики написания комментариев на Python
- Типы комментариев, которые вам может быть лучше избегать
- Как практиковать написание более чистых комментариев
Почему комментирование вашего кода так важно
Комментарии являются неотъемлемой частью любой программы. Они могут представлять собой документацию на уровне модулей или даже пояснения прямо внутри сложной функции.
Прежде чем погрузиться в различные типы комментариев, давайте взглянем поближе на то, почему комментирование вашего кода так важно.
Представьте две ситуации, в которых программист решил не комментировать свой код.
При чтении вашего собственного кода
Клиент А хочет последнюю минуту развертывания своего веб-сервиса. У вас уже сжатый срок, поэтому вы решаете просто сделать это. Все “лишнее” - документация, правильные комментарии и прочее - вы добавите позже.
Срок приходит, и вы развертываете сервис, вовремя. Уфф!
Вы делаете психологическую пометку о том, что вернетесь и обновите комментарии, но прежде чем они попадут в ваш список дел, ваш начальник приходит с новым проектом, с которым вам надо срочно начать. Через несколько дней вы полностью забыли, что должны были вернуться и правильно прокомментировать код, написанный для клиента А.
Проходит шесть месяцев, и клиент А требуется создать патч для того же сервиса, чтобы соответствовать новым требованиям. Вам поручено поддерживать его, так как это вы его первоначально создали. Вы открываете текстовый редактор и…
Что вы даже написали?!
Вы часами изучаете свой старый код, но теряетесь в этом беспорядке. Вы были в такой спешке в то время, что не назвали свои переменные правильно и даже не настроили свои функции в соответствующем управлении выполнением. И самое худшее - в скрипте нет комментариев, чтобы объяснить, что это такое!
Разработчики часто забывают, что делает их собственный код, особенно если он был написан давно или в условиях большого давления. Когда крайний срок быстро приближается, разработчики часто пишут выразительные комментарии, или они вообще не пишут никаких комментариев.
При чтении кода других людей
Программист Б передает вам проект, и вы должны проанализировать его и внести некоторые изменения. Код программиста Б был написан без надлежащих комментариев. Вы пытаетесь понять, что делает его код и как он работает, но потребуется гораздо больше времени и усилий, чем если бы в коде были хорошие комментарии.
Когда другие люди читают ваш код, им нужна информация, чтобы понять его логику и намерения, особенно если они не знакомы с вашим проектом. Хорошие комментарии помогают им разобраться в коде быстрее и легче.
Как писать комментарии на Python
Основы комментирования на Python
Комментарии на Python обычно начинаются с символа #. Все, что идет после этого символа в строке, считается комментарием и игнорируется интерпретатором Python.
Например:
# Это комментарий на PythonМногострочные комментарии на Python
Иногда вам может потребоваться написать более длинный комментарий, который простирается через несколько строк. Для этого вы можете использовать тройные кавычки (''' или """).
Например:
"""Этомногострочныйкомментарий"""Быстрые способы комментирования в Python
В некоторых случаях вам может потребоваться закомментировать целый блок кода. Вместо того, чтобы каждую строку отдельно комментировать, вы можете использовать быстрые сочетания клавиш в своей IDE для выделения блока кода и добавления символов # перед каждой строкой.
Лучшие практики комментирования на Python
При написании кода для себя или для других людей существуют некоторые лучшие практики для комментирования на Python:
При написании кода для себя
- Пишите комментарии, которые помогут вам облегчить вспомнить, что делает каждая часть кода, особенно в сложных местах или при использовании неочевидных решений.
- Избегайте комментирования очевидных или излишне подробных вещей, которые легко понять по коду самому. Комментарии должны служить как дополнительная информация, а не дублирование кода.
При написании кода для других людей
- Помните, что вы пишете для аудитории, которая может не знать вашего проекта так же хорошо, как вы. Объясните основные концепции и логику, на которых строится ваш код.
- Пишите комментарии, которые помогут другим разработчикам разобраться в вашем коде быстрее и легче. Объясните свои намерения и решения, особенно если они неочевидны.
Худшие практики комментирования на Python
Избегайте комментирования, которое содержит тупое или излишне очевидное
- Комментарии, которые описывают очевидные или тривиальные вещи, только загромождают ваш код и делают его менее читаемым. Лучше оставлять комментарии, которые действительно помогут разобраться в сложных местах.
Избегайте комментариев-кода и кодирования своих комментариев
- Некоторые разработчики любят использовать комментарии, чтобы хранить документацию или кодировать смысл переменных или функций. Помните, что комментарии должны быть дополнительной информацией, а не основным средством коммуникации. Хорошо выбирайте имена переменных и функций, чтобы они были понятны без дополнительных комментариев.
Избегайте грубых комментариев
- Комментарии, которые содержат оскорбления, негативные комментарии или непрофессиональное поведение, не должны быть частью вашего кода. Будьте вежливы и уважительны к другим разработчикам.
Как практиковать написание комментариев
Чтобы стать лучше в написании комментариев на Python, вы можете практиковать следующие стратегии:
- Добавляйте комментарии к вашему существующему коду, особенно в сложных или недокументированных частях. Пытайтесь объяснить каждую строку кода в своих комментариях.
- Читайте код других разработчиков и пробуйте разобраться в нем, не читая их комментарии. Затем сравните свои выводы с комментариями, чтобы увидеть, где вы правильно поняли код, а где возникли трудности.
Выводы
Комментарии являются неотъемлемой частью написания кода. Они помогают вам и другим разработчикам понять логику и намерения кода.
Правильные комментарии могут сэкономить вам много времени и усилий в будущем, помогая разбираться в сложных местах или облегчая чтение и понимание кода другим.
Так что не забывайте комментировать ваш код на Python и следовать лучшим практикам, чтобы сделать его более читаемым и понятным для всех.
