---
aliases:
  - комментирование кода
  - комментарии
tags:
  - maturity/🌱
date: 2024-11-24
---

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

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

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

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

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

   ```java
// 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)
   ```

Такие комментарии помогают быстрее ориентироваться в коде, особенно если он состоит из множества однотипных действий.
## Вредные комментарии в коде
Важно понимать, что не все комментарии полезны. Иногда они могут ухудшить [[Читаемый код|читаемость кода]] или ввести в заблуждение:

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

  ```python
  age = 14  # возраст
  ```

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

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

**Старый закомментированный код**: Закомментированный старый код часто остается в проекте и загромождает его. Если код больше не нужен, лучше удалить его, ведь все изменения сохраняются в системе контроля версий (например, Git).
***
## Мета информация
**Область**:: [[../meta/zero/00 Разработка|00 Разработка]]
**Родитель**:: 
**Источник**:: 
**Создана**:: [[2024-11-24]]
**Автор**:: 
### Дополнительные материалы
- 

### Дочерние заметки
<!-- QueryToSerialize: LIST FROM [[]] WHERE contains(Родитель, this.file.link) or contains(parents, this.file.link) -->