Документация как введение в программную архитектуру

Варианты применения архитектурной документации

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

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

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

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

Согласно одному из фундаментальных правил технической документации в общем и документации программной архитектуры в частности, составитель должен принимать позицию читателя. Без труда составленная, но трудная для восприятия (с точки зрения читателя — в данном случае заинтересованного лица) документация не найдет себе применения.

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

Среди заинтересованных лиц встречаются как умудренные опытом люди, гак и новички. Информация, которая им нужна, отличается не по содержанию, а по детализации — новичку она потребуется в «облегченном» виде. Архитектурная документация должна успешно вводить в курс дела всех, у кого есть такая потребность: новых разработчиков, инвесторов, временных участников проекта и т. д.

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

Однажды мне довелось делать презентацию атрибутного метода проектирования (Attribute Driven Design, ADD; см. главу 7). Заказчики — представители одного из подразделений крупной производственной компании — видели в действии большинство наших разработок: метод анализа компромиссных архитектурных решений (АТАМ, см. главу 11), реконструкцию (глава 10), а также наши предложения по линейкам продуктов (глава 14). Закончив вещать, я, весьма довольный собой, ждал реакции.

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

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

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

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

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

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

Таблица 9.1. Заинтересованные лица и их коммуникативные потребности, удовлетворяемые архитектурой¹

Заинтересованные лица	Способы применения
Архитектор и представляющие заказчика разработчики требований	Обсуждение конфликтующих требований и поиск компромиссов
Архитектор и проектировщики составляющих систему элементов	Разрешение состязаний за ресурсы, составление бюджета производительности и других бюджетов потребления ресурсов периода прогона
Конструкторы	Установление жестких ограничений применительно к нисходящим операциям разработки (и допустимых вольностей)
Тестировщики и сборщики	Регламентация корректного поведения совмещаемых элементов при тестировании методом «черного ящика»
Специалисты по сопровождению	Выявление областей влияния предполагаемых изменений
Проектировщики сторонних систем, взаимодействующих с рассматриваемой системой	Установление набора предоставляемых и требуемых операций, а также определение протокола их исполнения
Специалисты по атрибутам качества	Разработка модели, выступающей в качестве основы для функционирования аналитических инструментов: частотно-монотонного анализа возможности планирования в реальном времени, моделирования, имитационных генераторов, программ доказательства теорем, верификаторов и т. д. Подобные средства оперируют информацией о потреблении ресурсов, политиках планирования, зависимостях и т. п. Информации, содержащейся в документации архитектуры, должно быть достаточно для оценки различных атрибутов качества: безопасности, производительности, практичности, готовности и модифицируемости. Для анализа каждого из этих атрибутов характерны индивидуальные информационные потребности
Руководители Руководители линеек продуктов Группа контроля качества	Формирование групп разработчиков согласно установленному распределению функций, планирование и распределение ресурсов проекта, контроль действий, выполняемых различными группами Установление принадлежности или отклонения потенциального члена семейства продуктов от их области действия; при необходимости — определение степени отклонения Подготовка к проверке соответствия, призванной подтвердить соблюдение конструкторами архитектурных директив