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) -->
|
|||
|
|
|