В процессе разработки проектного решения мы, как правило вносим множество изменений. Нет, конечно есть проекты, где все требования жестко «приколочены гвоздями» в ТЗ и внесение каких‑либо изменений практически невозможно. Но большинство проектов в той или иной степени используют знаменитую методологию 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 позволяет сделать процесс документирования решений, принимаемых во время работы над проектом более удобным и полезным с практической точки зрения.
А технических писателей, которые только начинают документировать API и SDK приглашаем на бесплатный вебинар, который пройдёт уже 1.10. Регистрация доступна по ссылке.