65 lines
4.9 KiB
Markdown
65 lines
4.9 KiB
Markdown
---
|
||
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) -->
|
||
|