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

Код пишется для людей, а не для машин. Машины выполняют код без пояснений, но разработчикам важен контекст и намерение автора. Комментарии в коде помогают разработчикам быстрее понять написанный код.

Комментарии не заменяют полноценную документацию, но они являются дополнительным способом объяснить неочевидные моменты кода. Вот несколько ситуаций, когда комментарии могут быть особенно полезны:

Сложные или неочевидные участки кода. Например, регулярные выражения могут быть весьма сложными для понимания. Комментарий может объяснить, что делает регулярное выражение, делая код более доступным:

# Найти все слова, начинающиеся с буквы 'f'
f_words = re.findall('\bf\w+\b', text)
 
# Найти все слова, начинающиеся с буквы 'l'
l_words = re.findall('\bl\w+\b', text)

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

// SCORING
.withExternal().source(ApplicationState.SCORING).target(ApplicationState.CANCEL).event(ApplicationEvent.SCORING_FAILED)
.and()
.withExternal().source(ApplicationState.SCORING).target(ApplicationState.OFFER).event(ApplicationEvent.SCORING_PASSED)
.and()
 
// OFFER
.withExternal().source(ApplicationState.OFFER).target(ApplicationState.CANCEL).event(ApplicationEvent.OFFER_DENIED)

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

Вредные комментарии в коде

Важно понимать, что не все комментарии полезны. Иногда они могут ухудшить читаемость кода или ввести в заблуждение:

Избыточные комментарии: Если комментарий просто повторяет то, что уже очевидно из кода, он загромождает его и мешает сосредоточиться на важном. Вместо комментария лучше использовать осмысленное название переменной, чтобы само имя передавало значение. Например:

age = 14  # возраст

Здесь комментарий не добавляет ничего полезного, так как и так понятно, что переменная age обозначает возраст.

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

Старый закомментированный код: Закомментированный старый код часто остается в проекте и загромождает его. Если код больше не нужен, лучше удалить его, ведь все изменения сохраняются в системе контроля версий (например, Git).

Мета информация

Область:: 00 Разработка
Родитель::
Источник::
Создана:: 2024-11-24
Автор::

Дополнительные материалы

Дочерние заметки