В процессе разработки проектного решения мы, как правило вносим множество изменений. Нет, конечно есть проекты, где все требования жестко «приколочены гвоздями» в ТЗ и внесение каких‑либо изменений практически невозможно. Но большинство проектов в той или иной степени используют знаменитую методологию Agile, позволяющую проявлять гибкость при реализации проектов.

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

О пользе ADR

При рассмотрении ADR не стоит думать, что это какой‑то западный аналог наших ГОСТ 34 серии и аналогичных стандартов по документированию. В данном случае речь идет скорее о том, чтобы сделать принимаемые в процессе работы над проектом решения более прозрачными, то есть понятными для всей команды разработчиков. Записи ADR помогают команде прояснить, что она делает и почему. При этом важно сохранить эту аргументацию для людей, которые далее будут поддерживать и совершенствовать систему.

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

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

Дорогостоящая архитектура

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

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

Дизайн может содержать множество различных решений, однако изменение большинства из них могут обходиться команде разработчиков не слишком дорого. Например, переименование какого‑либо поля в интерфейсе приложения не является дорогостоящим изменением, хотя это тоже часть дизайна.

А вот если мы хотим что‑то поменять в архитектуре нашего решения, то такие изменения могут стоить довольно дорого, как в трудочасах, так и в реальных деньгах. Посмотрим несколько примеров различных дорогостоящих и не очень изменений, являющихся или не являющихся архитектурными решениями.

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

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

Но еще бывают дорогостоящ��е, но по сути, не архитектурные изменения. Например, замена одного основного компонента или подсистемы на другой с эквивалентной функциональностью. Примером этого может служить переход с одной базы данных на другую. Допустим мы выполняем переход с MS SQL на PostgreSQL. До тех пор, пока новый компонент/подсистема поддерживает те же фундаментальные концепции, что и старый, изменения не влияют на архитектуру системы. То есть, если структура таблиц, справочников и их связи останутся неизменными, а процедуры изменятся с точки зрения используемых команд и синтаксиса, но будут выполнять тот же функционал, что и в прежней БД, то в таком случае архитектура останется неизменной. Хотя и это изменение тоже может быть довольно дорогостоящим.

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

Детали реализации тоже не стоит путать с архитектурными решениями. Так выбор платформы пользовательского интерфейса, базы данных SQL или языка программирования для использования — это детали реализации, а не архитектурное решение. Все это важные решения, но они не поднимаются до уровня архитектурных решений.

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

 

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

Состав ADR

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

Существует несколько шаблонов записей ADR, некоторые из которых в большей или меньшей степени завязаны на специфику описываемого решения. Далее будут указаны основные разделы архитектурных записей. Вот список полей, которые могут быть в одной записи

Поле Статус — в нем мы указываем текущий статус данной записи, например, решение предложено, принято, отклонено, устарело, заменено и т. д.

В поле Контекст необходимо указать, какую проблему мы видим.

В поле Решение собственно указывается какие изменения для решения указанной проблемы мы предлагаем и/или осуществляем.

И поле Последствия содержит информацию об общем воздействии архитектурного решения. У каждого решения есть компромиссы и их нужно указать.

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

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

Заключение

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

Приглашаем вас ознакомиться с курсом «Технический писатель». В рамках обучения вы получите систематизированные знания и навыки, необходимые для работы с технической документацией.

Также рекомендуем обратить внимание на календарь открытых уроков, где вы можете познакомиться с материалами курса и форматом занятий.

Чтобы оставаться в курсе самых актуальных технологий и трендов, подписывайтесь на Telegram-канал OTUS.