Формат такой документации зависит от специфики проекта и может варьироваться от кратких заметок в текстовом документе, вики или блоге до формальных шаблонов, отражающих все аспекты каждого архитектурного решения. Независимо от вида и формата этот документ должен отвечать на следующие основные вопросы: «В чем суть принятого решения?» и «Почему мы приняли такое решение?». Еще один частый вопрос, ответ на который следует там отразить: «Какие альтернативные решения рассматривались и почему они были отвергнуты?» (на самом деле чаще спрашивают: «Почему не сделали так, как предлагал я?»). Документация должна предусматривать возможность поиска, чтобы при необходимости можно было легко найти требуемую информацию.
Такая документация может быть полезна во многих ситуациях:
Чтобы проинформировать разработчиков о важных архитектурных принципах, которые должны соблюдаться в работе.
Чтобы создать у членов команды единое видение проекта (и даже предотвратить бунт), когда разработчики ставят под сомнение логику архитектуры (а возможно, покорно принять критику, если решение действительно оказалось несостоятельным при ближайшем рассмотрении).
Чтобы продемонстрировать руководству и заинтересованным сторонам те причины, в силу которых программный продукт строится именно так, а не иначе (например, почему необходимо какое-нибудь дорогостоящее оборудование или программный компонент).
Чтобы передать проект новому архитектору (сколько раз, получая в наследство программный продукт, вы пытались понять, почему архитекторы поступили именно ТАК?).
Однако самые важные преимущества этой практики состоят в следующем:
Она заставляет вас явным образом формулировать свои доводы, проверяя их надежность (см. следующий этюд «Сомневайтесь в допущениях особенно в собственных»).
Она дает отправную точку для переоценки решений в случае изменения условий, от которых эти решения зависят.
По затрате усилий на подготовку такая документация сопоставима с заметками в ходе собраний или тематических обсуждений. Но какой бы формат вы ни выбрали, эти усилия окупятся.
Биография автора приведена ранее.
Сомневайтесь в допущениях особенно в собственных Тимоти Хай
Опыт архитекторов программного обеспечения свидетельствует о том, что следует документировать обоснования каждого принятого решения, особенно если решение подразумевает компромисс (между производительностью
и удобством сопровождения, между стоимостью и сроком выпуска продукта на рынок и т. п.). При более формальном подходе вместе с каждым решением регистрируется контекст, в котором оно принято, включая факторы, обусловившие окончательный выбор. Такими факторами могут быть не только функциональные или нефункциональные требования, но и факты (или «фактоиды» ), которые показались важными лицу, принимающему решение (ограничения технологий, квалификация работников, политическая среда и т. д.).
Практика документирования решений полезна тем, что перечисление этих факторов помогает выделить неявные допущения, которые влияют на важные решения относительно проектируемого продукта. Очень часто в основе этих допущений лежат «исторические причины», субъективные мнения, предубеждения разработчиков, опасения и сомнения и даже слухи:
«Продукты с открытым исходным кодом ненадежны».
«От индексов на основе битовых карт больше хлопот, чем пользы».
«Заказчик никогда не примет страницу, которая грузится по пять секунд».
«IT-директор согласится покупать продукты только у крупных вендоров».
Очень важно, чтобы такие допущения формулировались явно и четко (ради тех, кто придет нам на смену, а также для будущей переоценки). Но, пожалуй, еще важнее проследить за тем, чтобы любые предположения, не подкрепленные актуальными эмпирическими доказательствами (или подтверждениями от участников, если речь идет о политических факторах), были проверены до окончательного принятия решения. А вдруг заказчик согласится подождать пять секунд при построении важнейшего отчета, если вы добавите индикатор выполнения? В каком именно отношении и какой именно проект с открытым кодом ненадежен? А вы тестировали индексы на основе битовых карт на своих данных, используя запросы и транзакции своего приложения?
Обратите внимание на слово «актуальный». То, что было справедливо для старой версии вашей программы, может стать недействительным сегодня. Производительность индексов на основе битовых карт может различаться в разных версиях Oracle. Дыры в безопасности старой версии библиотеки могут быть уже исправлены в новой версии. Старый надежный производитель или поставщик может быть на последнем издыхании в финансовом отношении. Технологический ландшафт изменяется каждый день, меняются и люди. Кто знает, может, ваш IT-директор стал тайным поклонником Linux?
Факты и допущения это сваи, на которых строится ваш программный продукт. Позаботьтесь о том, чтобы эти сваи стояли на прочном фундаменте.
Биография автора приведена ранее.
Делитесь знаниями и опытом Пол У. Хомер
Если смотреть на вещи реалистично, наша база фундаментальных (то есть абсолютных и теоретически истинных) знаний о разработке программ мала по сравнению с тем, что необходимо для успешного развития проекта. Чтобы компенсировать эту нехватку знаний, мы строим догадки, полагаемся