Architecture Decision Records

Общее #

Architecture Decision Records (ADR) - это документы, которые описывают принятые архитектурные решения в проекте или системе. Они используются для сохранения и передачи информации о принятых решениях и обосновании их принятия.

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

Каждый ADR имеет уникальный идентификатор и может быть связан с другими ADR, которые зависят от него или на которые он влияет. Это помогает сохранять целостность и связность между принятыми решениями и облегчает понимание архитектуры системы.

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

Преимущества ADR включают:

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

Чтобы создать 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 в своих проектах.

Поделиться: