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

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

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

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

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

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

Кроме того, в каталоге обязательно должны разъясняться все элементы и отношения, значимые для данного представления, но по каким-то причинам не показанные в первичном отображении.

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

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

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

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

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

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

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

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

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

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