ADR (Architecture Decision Records) — это документы, которые описывают принятые архитектурные решения в проекте или системе. Они используются для сохранения и передачи информации о принятых решениях и обосновании их принятия.
Общая информация
Каждый Architecture Decision Records содержит информацию о принятом решении, его мотивации, альтернативах, которые были рассмотрены, и ограничениях, с которыми столкнулись при принятии решения. ADR также может включать информацию о влиянии решения на систему или проект, возможные риски и способы решения этих рисков.
Каждый ADR имеет уникальный идентификатор и может быть связан с другими ADR, которые зависят от него или на которые он влияет. Это помогает сохранять целостность и связность между принятыми решениями и облегчает понимание архитектуры системы.
ADR может быть использован как часть процесса принятия решений об архитектуре, чтобы обеспечить прозрачность и понимание мотиваций за принятие решений. Они также могут использоваться в качестве инструмента для обучения новых разработчиков о принятых решениях и как средство коммуникации между участниками проекта.
Преимущества Architecture Decision Records включают:
- Сохранение информации о принятых решениях, чтобы избежать повторения ошибок и упростить поддержку системы.
- Обеспечение прозрачности и понимания мотиваций за принятие решений.
- Облегчение коммуникации между участниками проекта.
- Помощь в обучении новых разработчиков о принятых решениях.
- Содействие устойчивости архитектуры системы.
Чтобы создать ADR, необходимо определить шаблон, в котором будут храниться принятые решения. Он может включать такие элементы, как заголовок, описание, мотивацию, альтернативы, решения и ссылки на связанные ADR. ADR можно хранить в системе контроля версий, чтобы обеспечить управление версиями и контроль доступа.
В целом, использование ADR является хорошей практикой в области разработки программного обеспечения, которая позволяет сохранять и передавать информацию о принятых архитектурных решениях. Они могут помочь управлять сложностью архитектуры, особенно в больших и длительных проектах, где принимаются множество решений, которые должны быть документированы и объяснены другим участникам команды. ADR также помогает установить четкую систему принятия решений, что может помочь обеспечить согласованность в разработке архитектуры.
В некоторых случаях, ADR может быть использованы для разрешения конфликтов, когда возникают несогласия по поводу архитектурных решений. Существование документированных принятых решений помогает устранить неопределенности и повысить уверенность в принятых решениях.
Одним из примеров использования ADR является проект Apache Cassandra. В этом проекте ADR используются для документирования принятых решений, которые затрагивают архитектуру и API, а также для обеспечения прозрачности и участия в принятии решений разработчиков из разных команд.
В целом, ADR представляют собой эффективный способ сохранения информации о принятых архитектурных решениях в проекте. Они помогают управлять сложностью архитектуры, обеспечивают прозрачность и понимание мотиваций за принятие решений, и могут использоваться в качестве инструмента для обучения и коммуникации между участниками проекта.
Пример ADR
Давайте рассмотрим пример описания ADR для решения связанного с выбором базы данных для проекта: В этом примере мы можем видеть, что ADR описывает контекст решения, само решение и его последствия. Это позволяет участникам проекта лучше понимать принятые решения и их мотивацию, а также предоставляет контекст для будущей работы и обновления решения.
Запись принятого решения № 1: Выбор базы данных для проекта
Дата: 2022-03-15
Контекст: Наш проект разрабатывается в команде, состоящей из 5 разработчиков, и представляет собой веб-приложение, предназначенное для онлайн-бронирования гостиничных номеров. Мы должны выбрать базу данных, которая будет использоваться для хранения данных, связанных с заказами, клиентами и отелями.
Решение: Мы решили использовать реляционную базу данных MySQL для хранения данных в нашем проекте. Мы выбрали MySQL из-за его высокой производительности, надежности, распространенности и знакомства с этой базой данных у большинства членов команды. Мы также обратили внимание на ее открытый исходный код, возможность масштабирования и широкие возможности по интеграции с другими инструментами.
Последствия: Это решение позволило нам начать разработку нашего проекта, используя выбранную базу данных. Мы начали разработку существенной части приложения, которая связана с базой данных, такие как схема базы данных, миграции и запросы к базе данных. Мы также сократили время, необходимое для обучения нового члена команды, так как большинство членов команды знакомы с MySQL.
Однако, это решение не является окончательным и может быть пересмотрено в будущем, если проект будет меняться или если появятся новые альтернативы, которые лучше подойдут для наших потребностей.
Основные элементы ADR
В документе должны быть описаны следующие основные моменты
- Заголовок. Заголовок документа должен содержать уникальный идентификатор для каждой записи принятых решений (например, “Запись принятого решения № 1: Выбор базы данных для проекта”).
- Дата. Дата, когда принято решение, должна быть указана в документе.
- Контекст. Опишите контекст, который привел к принятию решения. В этом разделе можно указать проблемы, требования, ограничения и другие факторы, которые были учтены при выборе решения.
- Решение. В этом разделе описывается конкретное решение, которое было принято. Это может включать в себя выбор конкретной технологии, дизайн-паттерна или архитектурного подхода.
- Последствия. Опишите последствия, которые могут возникнуть в результате принятого решения. Это может включать в себя плюсы и минусы выбранного решения, потенциальные проблемы, а также воздействие на существующие системы или процессы.
- Альтернативы. Если рассматривались альтернативные решения, их также необходимо описать. Это может включать в себя преимущества и недостатки каждой альтернативы, а также причины, по которым было выбрано конкретное решение.
- Ссылки. Если в процессе принятия решения были использованы внешние ресурсы, такие как статьи или исследования, они должны быть приведены в разделе ссылок.Документ ADR должен быть достаточно подробным и информативным, чтобы помочь участникам проекта понять, почему было принято конкретное решение, и как это решение повлияет на проект в целом.
Плюсы
Среди плюсов использования ADR можно выделить следующие:
- Документирование принятых решений. ADR позволяет документировать все решения, которые были приняты в ходе проекта, включая проблемы, требования, ограничения и альтернативные варианты. Это помогает сохранить целостность проекта и лучше понять его архитектуру.
- Легкость в использовании. Документ ADR обычно содержит достаточно информации, чтобы любой участник проекта мог легко понять, какие решения были приняты и почему. Это помогает сократить время на поиск и анализ принятых решений.
- Упрощение процесса принятия решений. Принятие решений становится более прозрачным и структурированным. ADR предоставляет методический подход к принятию решений и способствует принятию обоснованных решений.
- Облегчение передачи знаний. Документ ADR является хорошим способом передачи знаний между участниками проекта. Новые члены команды могут быстро ознакомиться с уже принятыми решениями, а также с контекстом, в котором они были приняты.
- Снижение рисков. ADR может помочь снизить риски, связанные с принятием решений, так как он позволяет принимать обоснованные и обдуманные решения, основанные на опыте, знаниях и контексте проекта.В целом, использование ADR помогает сделать процесс принятия решений более прозрачным, обоснованным и эффективным, что может улучшить качество проекта в целом.
Минусы
Хотя использование ADR имеет множество преимуществ, есть и некоторые недостатки:
- Дополнительные затраты на документирование. Создание и поддержка ADR требует времени и усилий, которые могут быть дополнительными затратами для проекта. Это может быть особенно сложно для небольших проектов или команд, где участников немного.
- Риск привязки к решениям в документе. Когда решения принимаются и документируются в ADR, это может привести к тому, что команда будет слишком жестко привязана к этим решениям. Это может создать проблемы, если изменения в контексте проекта потребуют изменения решений, описанных в ADR.
- Сложность поддержания. После того, как документ ADR был создан, он должен поддерживаться и обновляться по мере необходимости. Это может потребовать дополнительных усилий и внимания со стороны команды проекта.
- Недостаточная гибкость. Поскольку ADR документирует конкретные решения, это может ограничить возможность команды изменять свои подходы и методы, если это необходимо для достижения целей проекта.
- Сложность понимания. Если ADR написан неясно или недостаточно подробно, это может привести к тому, что участники проекта будут плохо понимать, какие решения были приняты и почему, что может затруднить работу команды.
В целом, использование ADR имеет свои преимущества и недостатки, и команды должны внимательно взвешивать эти факторы при принятии решения о том, следует ли использовать ADR в своих проектах.
Скопировано у Агальцова Антона — оригинал тут.
Добавить комментарий
Для отправки комментария вам необходимо авторизоваться.