# Decision 005 — Human Readable Comments

## Статус

**Accepted**

---

# Дата принятия

Принято во время разработки подсистемы **Market Intelligence**.

---

# Контекст

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

Даже технически корректный код может быть труден для сопровождения, если разработчику приходится самостоятельно догадываться:

- зачем существует компонент;
- какую задачу он решает;
- какие ограничения необходимо учитывать;
- почему архитектура построена именно таким образом.

Стандартные комментарии, объясняющие синтаксис Python, практически не помогают решить эти задачи.

---

# Проблема

Большинство комментариев в программных проектах описывают очевидные действия языка программирования.

Например:

```python
# увеличиваем счётчик
counter += 1
```

или

```python
# проверяем условие
if value > limit:
```

Подобные комментарии быстро устаревают и не помогают понять архитектуру системы.

Гораздо более ценными являются ответы на вопросы:

- зачем существует данный объект;
- почему принято именно такое решение;
- какие ограничения существуют;
- что произойдёт при нарушении данного правила.

---

# Рассмотренные варианты

## Вариант 1

Использовать минимальное количество комментариев.

### Преимущества

- меньше текста;
- проще поддерживать.

### Недостатки

- ухудшается сопровождаемость;
- сложнее понимать архитектуру;
- новые разработчики дольше погружаются в проект.

---

## Вариант 2

Комментировать синтаксис Python.

### Преимущества

- большое количество комментариев.

### Недостатки

- комментарии не несут архитектурной ценности;
- быстро устаревают;
- отвлекают от действительно важных пояснений.

---

## Вариант 3

Комментарии объясняют назначение компонента и архитектурный смысл.

### Преимущества

- легче сопровождать проект;
- проще понимать архитектуру;
- быстрее находить причины существования компонентов;
- комментарии остаются актуальными значительно дольше.

### Недостатки

- требуется больше внимания при проектировании.

---

# Принятое решение

Комментарии в Dzentra должны объяснять **назначение**, **роль** и **ограничения** компонентов.

Комментарии не должны пересказывать синтаксис языка Python.

---

# Основные правила

Комментарии должны отвечать хотя бы на один из следующих вопросов:

- зачем существует данный компонент;
- какую задачу он решает;
- почему используется именно такое решение;
- какие ограничения необходимо учитывать;
- где проходит граница ответственности компонента.

---

# Следует избегать

Не рекомендуется писать комментарии, объясняющие очевидные конструкции языка.

Например:

```python
# складываем два числа
total = a + b
```

или

```python
# возвращаем результат
return result
```

Такие комментарии не добавляют полезной информации.

---

# Комментарии в Market Intelligence

При разработке аналитических движков комментарии должны быть понятны разработчику, который не является профессиональным трейдером.

Предпочтительно использовать простые технические формулировки.

Если существует возможность заменить узкоспециализированный термин более понятным описанием без потери смысла, следует использовать более понятное описание.

---

# Причины принятия решения

Использование человекочитаемых комментариев позволяет:

- уменьшить порог входа в проект;
- повысить сопровождаемость;
- сделать архитектуру более понятной;
- уменьшить зависимость от автора исходного кода;
- сохранить знания внутри проекта.

---

# Последствия

После принятия настоящего решения:

- новые комментарии ориентируются на смысл, а не на синтаксис;
- архитектурные ограничения описываются непосредственно в коде;
- комментарии становятся частью инженерной документации проекта;
- разработчик может понять назначение большинства компонентов без обращения к внешним источникам.

---

# Связанные документы

- `architecture_principles.md`
- `development_process.md`
- `runtime_contract.md`

---

# История изменений

| Версия | Изменение |
|---------|-----------|
| 1.0 | Первое принятие архитектурного решения. |