Документирование представления

Стандартного шаблона документирования представлений не существует. Поэтому ниже речь пойдет о методике, доказавшей свою жизнеспособность в практической деятельности — стандартной семичастной структуре (seven-part standard organization). Во-первых, вне зависимости от того, каким разделам вы отдадите предпочтение, ввести стандартную структуру совершенно необходимо. Распределение информации по отдельным разделам помогает составителю документации уверенно приступить к решению задачи и установить момент ее выполнения; что же касается читателя, то ему становится проще быстро отыскать интересующую информацию и пропустить все ненужное.

1. Первичное отображение (primary presentation) содержит перечень элемен-
тов представления и установленные между ними отношения. В первичном
представлении должна содержаться (в форме словаря) та информация о си-
стеме, которую необходимо донести до читателя в первую очередь. Это, без
сомнения, основные элементы и отношения представления, хотя в некото-
рых случаях они могут быть отражены не полностью. К примеру, в первич-
ном отображении можно показать элементы и отношения, характерные для
нормального режима работы, а сведения об обработке ошибок или исклю-
чений представить во вспомогательной документации.

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

Иногда первичное отображение составляется в виде таблицы, которая по своему характеру прекрасно подходит для компактного представления больших объемов информации. Примером текстового первичного отображения является представление декомпозиции на модули системы А-7Е, изложенное в главе 3. Требование о кратком выражении наиболее значимых сведений о представлении распространяется и на текст. В разделе 9.6 мы намерены обсудить методы составления первичного отображения средствами языка UML.

2. Каталог элементов (element catalog) предназначен для более детального
описания элементов и отношений — как участвующих, так и не участву-
ющих в первичном отображении. Архитекторы часто совершают одну и ту
же ошибку — уделяя излишне серьезное внимание составлению первично-
го отображения, они забывают, что без дополнительной информации в нем
мало толку (Стараясь подчеркнуть роль первичного отображения как наброска документации представления, мы называем его архитектурным эскизом (architectural cartoon). К примеру, если на диаграмме показаны элементы А, В и С,
необходимо составить относительно детальное описание сущности этих
элементов, их назначения и ролей, причем разместить эту информацию
лучше всего в словаре представления. Скажем, для представления деком-
позиции на модули характерно наличие элементов-модулей, различных
вариантов отношения «является частью», а также свойств, определяющих
обязанности каждого модуля. В представлении процессов содержатся элементы-процессы, отношения, определяющие синхронизацию и другие механизмы межпроцессного взаимодействия, а также свойства с временными параметрами. Кроме того, в каталоге обязательно должны разъясняться все элементы и отношения, значимые для данного представления, но по каким-то причинам не показанные в первичном отображении. Чуть ниже мы обсудим еще два аспекта каталога элементов: поведение и интерфейсы элементов.

3. На контекстной диаграмме (context diagram) должно быть показано отношение изображенной в представлении системы к своему окружению из словаря представления. К примеру, представление «компонент и соединитель» подразумевает демонстрацию взаимодействия отдельных компонентов и соединителей с внешними компонентами и соединителями через посредство интерфейсов и протоколов.

4. Руководство по изменчивости (variability guide) демонстрирует способы применения изменяемых параметров, входящих в состав показанной в данном представлении архитектуры. В некоторых архитектурах принятие решений откладывается до более поздних стадий процесса разработки, что не отменяет необходимость в составлении документации. Примеры изменчивости обнаруживаются во всех линейках программных продуктов, архитектура которых предусматривает возможность создания множества конкретных систем (см. главу 14). В руководстве по изменчивости следует документировать все изменяемые параметры архитектуры, включая:

· альтернативы, рассматриваемые при принятии того или иного решения. В модульном представлении такими альтернативами являются различные варианты параметризации модулей. В представлении «компонент и соединитель» могут быть отражены ограничения по дублированию, планированию или выбору протоколов. В представлении распределения это условия назначения конкретного программного элемента тому или иному процессору;

· время связывания альтернатив. Одни решения принимаются в период проектирования, другие — в период производства, третьи — в период исполнения.

5. Предпосылки архитектурного решения (architecture background) — это раздел, в котором содержится обоснование отраженного в данном представлении проектного решения. Цель его — объяснить читателю, почему проект выглядит так, как он выглядит, и представить убедительные аргументы его превосходства. В состав этого раздела входят следующие элементы:

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

· результаты анализа, оправдывающие проектное решение и объясняющие последствия модификаций;

· отраженные в проектном решении допущения.

6. Глоссарий терминов (glossary of terms), применяемых в представлениях, и краткое описание каждого из них.

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