build 039: complete Quotes Feed migration foundation

docs/market_intelligence/decisions/decision-005-human-readable-comments.md

@@ -0,0 +1,198 @@
+# 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 | Первое принятие архитектурного решения. |