Ni boyinsha

Документирование представления
Стандартного шаблона документирования представлений не существует. Поэтому ниже речь пойдет о методике, доказавшей свою жизнеспособность в практической деятельности — стандартной семичастной структуре (seven-part standard organization). Во-первых, вне зависимости от того, каким разделам вы отдадите предпочтение, ввести стандартную структуру совершенно необходимо. Распределение информации по отдельным разделам помогает составителю документации уверенно приступить к решению задачи и установить момент ее выполнения; что же касается читателя, то ему становится проще быстро отыскать интересующую информацию и пропустить все ненужное.
1. Первичное отображение (primary presentation) содержит перечень элементов представления и установленные между ними отношения. В первичном представлении должна содержаться (в форме словаря) та информация о системе, которую необходимо донести до читателя в первую очередь. Это, без сомнения, основные элементы и отношения представления, хотя в некоторых случаях они могут быть отражены не полностью. К примеру, в первичном отображении можно показать элементы и отношения, характерные для нормального режима работы, а сведения об обработке ошибок или исключений представить во вспомогательной документации.
Как правило, первичное отображение составляется в графической форме. Дело в том, что большинство графических нотаций годятся только для первичного отображения — для всех остальных элементов документации они не приспособлены. Неизменным спутником графического представления должен быть перечень условных обозначений, содержащий объяснение использованной нотации и символики или хотя бы указывающий на источники получения этих объяснений.
2. Каталог элементов (element catalog) предназначен для более детального описания элементов и отношений — как участвующих, так и не участвующих в первичном отображении. Архитекторы часто совершают одну и ту же ошибку — уделяя излишне серьезное внимание составлению первичного отображения, они забывают, что без дополнительной информации в нем мало толку1. К примеру, если на диаграмме показаны элементы А, В и С, необходимо составить относительно детальное описание сущности этих элементов, их назначения и ролей, причем разместить эту информацию лучше всего в словаре представления. Скажем, для представления декомпозиции на модули характерно наличие элементов-модулей, различных вариантов отношения «является частью», а также свойств, определяющих обязанности каждого модуля. В представлении процессов содержатся эле менты-процессы, отношения, определяющие синхронизацию и другие механизмы межпроцессного взаимодействия, а также свойства с временными параметрами.
Кроме того, в каталоге обязательно должны разъясняться все элементы и отношения, значимые для данного представления, но по каким-то причинам не показанные в первичном отображении.
Чуть ниже мы обсудим еще два аспекта каталога элементов: поведение и интерфейсы элементов.
3. На контекстной диаграмме (context diagram) должно быть показано отношение изображенной в представлении системы к своему окружению из словаря представления. К примеру, представление «компонент и соединитель» подразумевает демонстрацию взаимодействия отдельных компонентов и соединителей с внешними компонентами и соединителями через посредство интерфейсов и протоколов.
4. Руководство по изменчивости (variability guide) демонстрирует способы применения изменяемых параметров, входящих в состав показанной в данном представлении архитектуры. В некоторых архитектурах принятие решений откладывается до более поздних стадий процесса разработки, что не отменяет необходимость в составлении документации. Примеры изменчивости обнаруживаются во всех линейках программных продуктов, архитектура которых предусматривает возможность создания множества конкретных систем. В руководстве по изменчивости следует документировать все изменяемые параметры архитектуры, включая:
О альтернативы, рассматриваемые при принятии того или иного решения. В модульном представлении такими альтернативами являются различные варианты параметризации модулей. В представлении «компонент и соединитель» могут быть отражены ограничения по дублированию, планированию или выбору протоколов. В представлении распределения это условия назначения конкретного программного элемента тому или иному процессору;
О время связывания альтернатив. Одни решения принимаются в период проектирования, другие — в период производства, третьи — в период исполнения.
5. Предпосылки архитектурного решения (architecture background) — это раздел, в котором содержится обоснование отраженного в данном представлении проектного решения. Цель его — объяснить читателю, почему проект выглядит так, как он выглядит, и представить убедительные аргументы его превосходства. В состав этого раздела входят следующие элементы:
О логическое обоснование, демонстрирующее предпосылки принятия проектных решений, отраженных в данном представлении, и причины отказа от альтернатив;
О результаты анализа, оправдывающие проектное решение и объясняющие последствия модификаций;
О отраженные в проектном решении допущения.
6. Глоссарий терминов (glossary of terms), применяемых в представлениях, и краткое описание каждого из них.
7. Другая информация. Содержание этого раздела зависит от методов работы конкретной организации. В частности, здесь можно разместить административные сведения: авторство, данные управления конфигурациями и история изменений. Кроме того, архитектор волен разместить здесь систему ссылок на отдельные разделы сводки требований. Таким образом, речь идет об информации, которая, строго говоря, не имеет прямого отношения к архитектуре, но которую удобнее всего привести вместе с архитектурными сведениями. Для этого и предназначен рассматриваемый раздел. В любом случае, в его вступительной части необходимо поместить содержание.