Достаточно часто находил у себя и видел у других огромное желание, при присоединении к новому проекту, предложить улучшение или постараться исправить уже имеющуюся систему.
Это нормально, мы понимаем и видим как можно сделать лучше, наш глаз не замылен и мы стремимся поскорее с головой ворваться в новый проект.
Вот только один момент мы не учиваем: "А почему это сделано именно так и почему это никто не спешит исправить?".
Можно, конечно, все объяснить простым конформизмом и ленью, но чаще всего мы упускаем одну простую мысль.
Когда-то уже кто-то взял ответственность и принял решение.
Не принимать решение - это тоже решение.
И получается что прежде чем предложить изменение, нужно понять контекст текущего решения. А чтобы потом кто-то такой же смелый не переписал уже твоё — этот контекст нужно зафиксировать.
🔸Проблема: устные договорённости
Классический сценарий: обсуждаете с командой, как лучше встроить новый модуль. В чате или на созвоне находите оптимальное решение, все соглашаются — но ничто не фиксируется письменно.
Через две недели часть команды уже не помнит деталей обсуждения, другие уверены, что договорились о другом, а новый участник не понимает причины выбора.
В итоге любое устное или не зафиксированное решение будет пересматриваться и, скорее всего, переписываться заново — просто потому, что отсутствует общий ориентир.
А как мы знаем, архитектура — это набор ключевых решений. Но решения без зафиксированного контекста — просто факты без объяснения.
🔸ADR: формат
В 2011 Michael Nygard предложил формат Architecture Decision Records (ADR).
Формат минимален:
▫️ Status — proposed, accepted, deprecated, superseded
▫️ Context — какая ситуация и ограничения привели к решению
▫️ Decision — что именно решили
▫️ Consequences — что из этого следует, включая негативные эффекты
🔹Ключевое: ADR фиксирует не "что мы сделали", а "почему мы так решили".
🔸Правила ведения
▫️Каждый документ включает только одно решение
▫️Информация из ADR при изменениях не удаляется — статус меняется на deprecated или superseded, создаётся новый ADR со ссылкой
▫️Файлы максимально атомарные и легковесные — пара параграфов
▫️Хранятся в системе контроля версий рядом с кодом, не в wiki
Для Unity-проекта: папка ADR в корне репозитория.
Пример формата из реального open-source проекта C4G — ADR прямо в корне репозитория.
Таким образом у вас важная техническая документация всегда под рукой в близкой доступности к проекту. Не нужно время тратить на поиск в wiki.
🔸ADR и проектирование
ADR дополняет C4: уровни System/Container/Component показывают что и как устроено, ADR объясняет почему именно так.
Требования определяют что система должна делать. ADR фиксирует как мы решили это реализовать и какие альтернативы отвергли.
При этом зафиксированные решения в ADR — это чаще всего ответы на сложные технические вопросы, которые удовлетворяют именно нефункциональным требованиям.
И по моим наблюдениям, именно неучтённые нефункциональные требования чаще всего раздувают изначальные сроки.
Если кто-то придёт и скажет "давайте использовать нативные okhttp и alamofire" — а у тебя ADR:
Status: accepted.
Context: нужен кроссплатформенный HTTP на iOS/Android/WebGL.
Decision: используем BestHTTP.
Хочешь менять — сделай исследование, обоснуй, создай новый ADR, примите решение, внесите изменения.
🔻 ADR — минимальная документация с максимальной отдачей. Контекст, решение, последствия — пара параграфов сейчас экономит часы обсуждений и обоснований через полгода.
Для примера можете посмотреть:
▫️Как структурированы предложения фичей для языка C#
▫️Простой шаблон ADR, что я упомянул в статье
▫️Как мы описываем ADR'ы на проекте, который создан на курсе
Ставь 👍 если тебе заходит такого рода контент!
Ты знаешь кому переслать эту статью 💪
#проектирование@UniArchitect