4.9 KiB
| aliases | tags | date | |||
|---|---|---|---|---|---|
|
|
2024-11-24 |
Читаемый код. Машины выполняют код без пояснений, но разработчикам важен контекст и намерение автора. Комментарии в коде помогают разработчикам быстрее понять написанный код.
==Комментарии не заменяют полноценную документацию, но они являются дополнительным способом объяснить неочевидные моменты кода.== Вот несколько ситуаций, когда комментарии могут быть особенно полезны:
Сложные или неочевидные участки кода. Например, регулярные выражения могут быть весьма сложными для понимания. Комментарий может объяснить, что делает регулярное выражение, делая код более доступным:
# Найти все слова, начинающиеся с буквы '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).
Мета информация
Область:: ../meta/zero/00 Разработка Родитель:: Источник:: Создана:: 2024-11-24 Автор::