Одна из разновидностей документации, которая почти не устаревает, не требует особых усилий по подготовке и почти всегда окупается, — запись обоснований, стоящих за теми или иными архитектурными решениями. Как объясняет Марк Ричардс в этюде «Архитектурные компромиссы», создание архитектуры программного продукта по сути сводится к поиску разумных компромиссов между различными характеристиками качества, затратами, временем и другими факторами. Вам, руководству, разработчикам и другим заинтересованным в проекте сторонам должно быть абсолютно ясно, почему одному решению отдано предпочтение перед другим и к каким компромиссам это привело. (Вы пожертвовали горизонтальной масштабируемостью ради сокращения затрат на оборудование и лицензии? Проблемы безопасности настолько серьезны, что оправдывают увеличение времени отклика ради шифрования данных?)

Формат такой документации зависит от специфики проекта и может варьироваться от кратких заметок в текстовом документе, вики или блоге до формальных шаблонов, отражающих все аспекты каждого архитектурного решения. Независимо от вида и формата этот документ должен отвечать на следующие основные вопросы: «В чем суть принятого решения?» и «Почему мы приняли такое решение?». Еще один частый вопрос, ответ на который следует там отразить: «Какие альтернативные решения рассматривались и почему они были отвергнуты?» (на самом деле чаще спрашивают: «Почему не сделали так, как предлагал я?»). Документация должна предусматривать возможность поиска, чтобы при необходимости можно было легко найти требуемую информацию.

Такая документация может быть полезна во многих ситуациях:

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

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

• Чтобы продемонстрировать руководству и заинтересованным сторонам те причины, в силу которых программный продукт строится именно так, а не иначе (например, почему необходимо какое-нибудь дорогостоящее оборудование или программный компонент).

• Чтобы передать проект новому архитектору (сколько раз, получая в наследство программный продукт, вы пытались понять, почему архитекторы поступили именно ТАК?).

Однако самые важные преимущества этой практики состоят в следующем:

• Она заставляет вас явным образом формулировать свои доводы, проверяя их надежность (см. следующий этюд «Сомневайтесь в допущениях — особенно в собственных»).

• Она дает отправную точку для переоценки решений в случае изменения условий, от которых эти решения зависят.

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

Биография автора приведена ранее.

Закон отложенных решений Уэзерна гласит: «Допущения — корень всех провалов». Конечно, формулировка не очень серьезная, но когда предположения обходятся вам в несколько тысяч (а то и миллионов) долларов, становится не до смеха.

Опыт архитекторов программного обеспечения свидетельствует о том, что следует документировать обоснования каждого принятого решения, особенно если решение подразумевает компромисс (между производительностью и удобством сопровождения, между стоимостью и сроком выпуска продукта на рынок и т. п.). При более формальном подходе вместе с каждым решением регистрируется контекст, в котором оно принято, включая факторы, обусловившие окончательный выбор. Такими факторами могут быть не только функциональные или нефункциональные требования, но и факты (или «фактоиды» [32] …), которые показались важными лицу, принимающему решение (ограничения технологий, квалификация работников, политическая среда и т. д.).

Практика документирования решений полезна тем, что перечисление этих факторов помогает выделить неявные допущения, которые влияют на важные решения относительно проектируемого продукта. Очень часто в основе этих допущений лежат «исторические причины», субъективные мнения, предубеждения разработчиков, опасения и сомнения [33] и даже слухи:

• «Продукты с открытым исходным кодом ненадежны».

• «От индексов на основе битовых карт больше хлопот, чем пользы».

• «Заказчик никогда не примет страницу, которая грузится по пять секунд».

• «IT-директор согласится покупать продукты только у крупных вендоров».

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