Народ, всем привет. Комментирование кода — это важный навык, который одним нравится, другим нет. Но он точно помогает разработчикам лучше понимать свою работу, а также делает код более читаемым и удобным для поддержки. Правильные комментарии позволяют избежать путаницы, ускоряют процесс разработки. И уж что говорить о том, что они быстро помогают разобраться во всей этой портянке, что вы накатали пару лет назад, и вдруг вам понадобилось что-то там подправить или обновить. Сколько раз я на это попадался, и сколько раз я радовался, что комментирую свой код. Правда не всегда удачно.
Поэтому, сегодня, мы рассмотрим лучшие практики комментирования кода, может разберем какие-то примеры на разных языках программирования. И возможно, но это не точно, поймем для себя, как же лучше, правильнее и практичнее писать комментарии к своему коду. И в начале скажу важный совет – комменты нужно писать сразу по мере написания кода, а не «потом, когда все напишу». Это так не работает. Но при этом точно также не стоит злоупотреблять комментариями, особенно если код сам по себе достаточно понятен.
1. Комментируйте зачем, а не как. Суть тут в том, что не надо писать очевидные вещи, что и так понятно из действия. Лучше всего написать, что произойдет потом, или для чего это было нужно. Вот пример плохого комментария, где он сам по себе излишен:
# Увеличиваем x на 1
x += 1
А вот как надо было. Здесь поясняется причина изменения переменной, а не очевидное действие.
# Увеличиваем счетчик, чтобы отслеживать количество попыток
attempts += 1
2. Используйте понятный язык. Комментарии должны быть простыми и понятными, и не только вам, кто погружен сейчас в проект или понимает какие-то термины, обозначения. Но и начинающему разработчику, например. Помните, что баги в коде или минимальные правки вносят обычно Джуны.
3. Следите за актуальностью. Со временем код может меняться, и, если комментарии не обновлять, они могут ввести в заблуждение. Поэтому, изменили что-то, внесли правки, что-то поправили, даже в режиме жесткого дедлайна, заложите еще пять минут и опишите правку.
Кстати, Вам может быть это интересно:
4. Избегайте избыточных комментариев. Если код написан понятно и его легко прочитать без комментариев, то лучше их даже и не добавлять. Если у вас есть строка кода, где вы просто присваиваете переменной какое-то значение (а саму переменную вы уже описали где-то выше), то не надо тут лишних строк и пояснений.
# Присваиваем переменной a значение 10
a = 10
5. Используйте комментарии для сложной логики. Вместо того чтобы комментировать каждую строку, объясните сложный участок кода в целом. Хоть портянку напишите, но часто одним длинным предложением или абзацем станет гораздо понятнее, если в ней заложить логику, объяснить принцип действия.
# Определяем, является ли строка палиндромом, игнорируя регистр и пробелы
s = ''.join(filter(str.isalnum, s.lower()))
if s == s[::-1]:
print("Палиндром")
6. Придерживайтесь стиля. Используйте единообразный стиль комментариев во всем проекте. Это улучшает читаемость кода. Это касается и разделителей, и отступов, и каких-то значков, и даже стилистики написания самого текста.
Что комментировать по итогу?
Получается, если подытожить все вышесказанное, то комментировать нужно не сам код как действие, а в основном логику, важные алгоритмы и нестандартные решения. Конечно, может быть и более простые комментарии, если здесь явно какой-то неочевидный момент, а может вообще вы использовали «костыль» и у вас ограничения и допущения в коде. Ну и на практике места, требующие доработки (типа лист TODO), хотя вернетесь вы к нему потом или нет – большой вопрос.
А вот чего избегать в комментариях, так это их избыточности, особенно к очевидному коду. Каких-то избыточных пояснений, не относящихся к делу. А также устаревших, если вы их не обновляете. Помните, что правильное комментирование кода делает разработку проще и эффективнее. Следуйте лучшим практикам, держите комментарии актуальными и пишите их так, чтобы они помогали, а не запутывали. Хорошо комментированный код — это показатель профессионализма разработчика.
Кстати, у нас есть и другой канал, FIT FOR FUN, про фитнес, бодибилдинг, правильное питание, похудение и ЗОЖ в целом. Кому интересно, ждем вас в гости!