При написании кода в Python, комментарии часто являются недооцененным, но в тоже время важным инструментом. Они помогают разработчикам, как себе, так и другим, понять архитектуру и логику написанной программы. В этой статье мы обсудим, какие бывают комментарии в Python, как их правильно оформлять и когда они необходимы.
Важность комментариев
Комментарии в Python игнорируются интерпретатором и не влияют на выполнение кода. Тем не менее, они жизненно важны для разработчиков. Комментарии служат для описания цели кода, предоставления контекста и делают код более понятным для других людей, даже если это вы сами спустя несколько месяцев после написания кода.
Комментарии добавляются, обычно, для себя или других разработчиков.
Типы комментариев
Однострочные комментарии
Однострочные комментарии начинаются с символа решётки #. Они используются для кратких пояснений и обычно пишутся сверху или сбоку от строки кода.
- Первая строка начинается с # и объясняет, для чего нужна следующая функция.
- Вернувшееся значение будет равно 8, и это указано после решётки по окончанию кода выражения.
Многострочные комментарии
Многострочные комментарии могут быть написаны с помощью нескольких строк, каждая из которых начинается с #.
Многострочные комментарии пишутся с несколькими знаками решётки и расположены на разных строках.
Комментарии в конце строк
Иногда комментарии пишут сразу в конце строки с кодом, с использованием двух пробелов перед символом #.
x = 10 # Устанавливаем значение переменной x в 10
Третий тип комментариев — это за строками кода. Они указываются после строки с кодом, после двух пробелов и указания знака решётки.
Докстринги
Докстринги — это многострочные комментарии, заключенные в тройные кавычки (""" или '''), обычно используемые для создания документации к функциям и классам.
Это четвёртый тип многострочных комментариев, который находится между тройными одинарными, либо тройными двойными кавычками. Используются в функциях для описания того, что функция делает.
Рекомендации по использованию комментариев
- Обычно в комментариях пишут рекомендации по использованию кода, либо цель исполнения того или иного кода. Не нужно описывать то, что код делает. Сам по себе, код должен быть и без комментариев хорошо понятен и читабелен.
- Пишите осмысленные комментарии: Комментарии должны объяснять, зачем написан конкретный блок кода, а не то, что он делает. Код должен быть понятным благодаря хорошему именованию переменных и функций.
- Держите код и комментарии актуальными: Если вы изменяете код, не забудьте обновить и комментарии, чтобы избежать путаницы.
- Не допускайте избыточность комментариев: Не стоит комментировать всё подряд. Если код очевиден и прост, комментарии лучше опустить.
- Используйте докстринги для функций и классов: Это улучшит вашу документацию и сделает код более поддерживаемым.
Заключение
Корректное использование комментариев помогает другим программистам легко понять ваш код и ваше намерение. Следуйте приведённым выше рекомендациям, чтобы улучшить свой код и сделать его более доступным для будущих изменений и командной работы. Комментарии — это не просто текст. Это мост между вашим кодом и людьми, которые будут с ним работать.
Полезные ресурсы:
Сообщество дизайнеров в VK
https://vk.com/grafantonkozlov
Телеграмм канал сообщества
https://t.me/grafantonkozlov
Архив эксклюзивного контента
https://boosty.to/antonkzv
Канал на Дзен
https://dzen.ru/grafantonkozlov
---------------------------------------
Бесплатный Хостинг и доменное имя
https://tilda.cc/?r=4159746
Мощная и надежная нейронная сеть Gerwin AI
https://t.me/GerwinPromoBot?start=referrer_3CKSERJX
GPTs — плагины и ассистенты для ChatGPT на русском языке
https://gptunnel.ru/?ref=Anton
---------------------------------------
Донат для автора блога