Документация компромиссов
Тема дорожной карты · Software Architecture
Документация компромиссов — одна из ключевых частей любого ADR, но часто пропускаемая. Тем не менее, именно эта секция позволяет будущим читателям оценить, какое решение было принято и какие последствия это имело. Важность этого шага не заключается только в текущем контексте, но и в долгосрочной перспективе, когда эти компромиссы могут стать критически важными для понимания истории проекта и принятия новых решений.
Как это работает
В секции Consequences следует указать 2-4 конкретных компромисса. Для каждого компромисса важно четко определить, что выигрываем и что отдаём. Например, можно указать: 'мы принимаем более медленные записи в обмен на сильную консистентность' или 'мы принимаем lock-in вендора в обмен на скорость выхода на рынок managed-сервиса'. Важно также указывать, как эти компромиссы влияют на атрибуты качества, такие как доступность, надежность, масштабируемость и другие. Это помогает читателям лучше понять, какое решение было принято и какие последствия это имело.
Когда применять
При написании ADR для решения с реальными альтернативами, всегда следует документировать компромиссы. Если вы выбрали определенный вариант, но не упомянули другие доступные альтернативы, это может привести к неправильному пониманию ситуации. Например, если вы выбрали микросервисную архитектуру, но не упомянули монолитную архитектуру как альтернативу, это может ввести в заблуждение будущих читателей. У большинства решений есть альтернативы, и их следует документировать, чтобы обеспечить полное понимание всех возможных вариантов.
Типичные ошибки
(1) Нет секции компромиссов — это самый частый провал при написании ADR. Вместо того чтобы документировать все аспекты принятия решения, ADR может выглядеть как простое объявление, а не как результат тщательного анализа и обсуждения. (2) Компромиссы без называния альтернативы — указание только на то, что выигрываем, без упоминания отдающегося, может создать искаженное представление о решении. Например, 'мы принимаем более медленные записи' без упоминания 'в обмен на отказ от альтернативы X'. (3) Асимметричный фрейминг — перечисление всех положительных следствий только для выбранной альтернативы и всех отрицательных только для альтернатив может ввести в заблуждение будущих читателей. Это делает анализ несправедливым и необъективным.