Проектирование программных систем. Занятие 8

МАИ, каф 806, ППС

Документирование архитектуры

1


Документирование архитектурыПравило №1

Пиши документы с точки зрения читателей.

Дейкстра (1930–2002) говорил, что стоит потратить пару часов что бы сделать отдельно взятое предложение в документе проще.

Нужно понять, кто читатель документации и что он ждет от неё. Нужно понимать что читатели знают.

Нужно понимать на какие вопросы отвечают определенные секции документа. Документ должен иметь четкий план изложения

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

Сокращения хороши для военных методичек, но не для реальных документов.

2



Избегайте повторений.

Каждая информация должна быть записана только в одном месте. Это упрощает использование и модифицирование документа.

Самое страшное если одна и та же информация появляется в двух местах в разных формах, это может серьезно запутать читателя.

Используйте в документах ссылки и hyperlink

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

3



Избегайте двусмысленности.

Она появляется, когда документ может быть интерпретирован несколькими способами.

Рецензирование документа членами команды хорошо позволяет выявить двусмысленность.

Объясняйте нотацию в которой пишется документ.

Помните, что диаграммы могут быть двусмысленными.

Самый верный признак истины - это простота и ясность. Ложь всегда бывает сложна, вычурна и многословна. /Л.Толстой/

4



Используйте стандартную структуру документа (шаблон).

Это помогает пользователю ориентироваться в документе и упрощает поиск нужных пунктов.

Помогает писателю планировать работу над документом.

Помогает записывать информацию сразу как она будет известна (например мы можем заполнить вначале 3ую секцию, а потом первые две)

Показывает, какие работы ещё осталось выполнить (например, помеченные как TBD).

Позволяет судить о полноте документа (если шаблон документ описывает все аспекты)

5



Всегда описывайте причину, по которой принимаются те или иные решения.

Можно так же описать альтернативные решения, которые вы отбросили, и описать почему это сделали.

Описанное обоснование решения экономит много времени и Вам и читателю.

Нужно всегда помнить, что через пол года даже Вы забудете, почему принималось такое решение.

6



Поддерживайте документ актуальным (но не очень)

Документы, которые не актуальные – ни кто не использует.

Актуальные документы все любят использовать (потому что там проще найти ответы на вопросы).

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

7



Проверяйте документ на соответствие целям.

Только пользователи документа могут Вам сказать, что в нем есть нужная информация и она представлена в нужном виде.

Перед тем как сделать финальный документ. Обязательно обсудите его с командой.

8


ИНТЕРФЕЙСЫдокументирование

9


ИнтерфейсыЧто важно помнить?

Элементы программного обеспечения обладают интерфейсами.

Интерфейс – это способ взаимодействия элемента с внешним миром.

Интерфейс элемента отделен от его реализации.

Элемент может иметь множество интерфейсов.

Для поддержки различной функциональности.

Для поддержки эволюции интерфейсов.

Элемент не только предоставляет интерфейсы но и может требовать их для корректной работы.

Несколько внешних систем могут взаимодействовать с интерфейсом в одно и то же время.

10


ИнтерфейсыGuideline по документированию

Фокусируйтесь на том как интерфейс взаимодействует с окружающей средой, а не на том как он реализован.

Интерфейс должен предоставлять только ту информацию, которую внешние системы должны знать. Как только вы предоставляете какую-то информацию, то сразу внешние системы начинают от неё зависеть и Вы уже не сможете её поменять.

Помни для кого документируешь интерфейс:

Для разработчика из соседней команды – достаточно минимума информации.

Для коммерческого API нужна как можно более полная информация.

Будь как можно более конкретен и точен

11


ИнтерфейсыПоследовательная детализация информации.

В начале процесса проектирования

Определяется последовательность взаимодействий элементов

Потоки данных

Формируются сервисы

Границы модулей определены

Определяется семантика интерфейса, его параметры, поведение.

Модуль разработан

Описывается уточнённый синтаксис интерфейса и уточненные детали

12


ИнтерфейсыИз чего состоят?

Interface Identity

Описывает идентификацию интерфейса с точки зрения языка программирования.

Например: OutputObject Method (InputObject parameter)

Описание ресурсов, предоставляемых интерфейсом

13

class PromisedPayment

IL.DomainModel::Payment

+ PaymentId: UniqueIdentifier+ Amount: double+ InternalAmount: double+ DateOfPayment: DateTime+ DateOfTransaction: DateTime+ PaymentDocumentNumber: string+ PaymentType: string+ Currency: Currency+ Parameters: PaymentParameters

PromisedPayment

+ Status: PromisedPaymentStatusEnum+ Channel: ChannelEnum+ ExpiredDate: DateTime?+ StornoReason: BaseDictionary


ИнтерфейсыРесурсы – что это?

Ресурсами могут быть как операции/методы так и данные.

Синтаксис ресурса

Семантика ресурсаЧто будет если вызвать ресурс? Как и какие данные поменяются? Как изменится поведение?

У переменных появились новые значения(например у возвращаемого результата)

Изменение в видимом состоянии элемента

События, которые появились в результате использования ресурса

Побочные эффекты

Результат, видимый человеком (например, программа закрылась)

Синхронное или асинхронное использование ресурса

Ограничение на использование ресурса (параметры, состояние элемента)

Обработка ошибок

Неправильные параметры, внутренние ошибки, бизнес-ошибки, ошибки среды передачи (разрывы соединения)

14


ИнтерфейсыРесурсы – guideline

Описывайте только тот результат использования ресурса, который заметен снаружи элемента.

Попробуйте описать семантику использования интерфейса, в терминах его использования: если положить элемент в стэк методом push то потом он доступен методом pop

Избегайте слов с «двойным толкованием», таких как «может». Будьте точными.

Описывайте все предположения о параметрах (точность, диапазоны значений, зависимости между параметрами)

Если нужно приводить пример использования, то делайте это отдельно от описания ресурса. Если примеры описывать рядом, то пользователь может предположить что ресурс можно использовать только указанным способом.

Никогда не приводите описания того как ресурс реализуется.

Не забывайте об атрибутах качества

Количество запросов в единицу времени, время отклика, скорость работы и т.д.

15


ИнтерфейсыКому интересны?

Разработчик элемента

Тестировщик

Разработчик системы, использующей данный элемент

Аналитик

Архитектор

Руководитель проекта

16


Architecture Tradeoff Analysis Method

"Cheshire-Puss," [Alice] began, rather timidly … "Would you tell me, please, which way I ought to go from here?" "That depends a good deal on where you want to go to," said the Cat. "Oh, I don't much care where—" said Alice. Then it doesn't matter which way you go," said the Cat. "—so long as I get somewhere," said Alice. "Oh, you're sure to do that," said the Cat, "if only you walk long enough."

—Lewis Carroll, Alice's Adventures in Wonderland.

17


LAAMLightweight Architecture Alternative Assessment Method

Сравниваем архитектурные решения с точки зрения качества.

18



Измеримые сценарии

19



Определяем, приоритеты сценариев

20



Определяем вес сценария

21



Альтернативы

22

Scenario Weight Alternative 1 Alternative 2 Alternative 3

Scenario 1 .140625 Poor (0) Fair (1) Excellent (4)

Scenario 2 .046875 Good (3) Adequate (2) Fair (1)

Total .140625 .234375 .609375


Architecture Tradeoff Analysis Methodкомандный метод оценки архитектуры

23


Architecture Tradeoff Analysis Methodучастники

24

Роль Ответственность Характеристика

Team Leader Организует мероприятие, контактирует с клиентом, убеждается что все потребности клиента выполнены, формирует команду.

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

Evaluation Leader

Проводит мероприятие, создает сценарии, управляет выбором и приоритезацией сценариев

Хорошее понимание архитектурных проблем, умение управлять темой дискуссии

Scenario Scribe Записывает найденные сценарии и согласует формулировки сценариев

Умение выделить суть в технических обсуждениях

Processing Scribe

Создает описание процесса в электронной форме, описывает причины возникновения сценария

Хорошее понимание архитектурных проблем, быстрая печать

Time Keeper Определяет сколько времени тратится на обсуждение сценариев

Умеет прерывать дискурсии

Process Observer

Следит за процессом в целом, делает выводы о том как процесс может быть улучшен

Большой опыт в оценке архитектуры

Process Enforcer

Помогает идти по шагам процесса оценки архитектуры Хорошо разбирается в процессе оценки

Questioner Определяет важные вопросы и точки риска Разбирается в архитектуре и требованиях спонсоров


Architecture Tradeoff Analysis Methodрезультаты

Краткое изложение архитектуры.Доступной для изложения в течении одного часа.

Формулировки бизнес-целей.Зачастую все участники видят бизнес-цели первый раз.

Атрибуты качества в виде перечня сценариев.

Связь архитектурных решений с атрибутами качества.

Набор точек «компромисов».Обычно они связаны с решениями, которые затрагивают несколько атрибутов качества.

Перечень рисков. Набор архитектурных решений, которые могут повлечь негативное влияние на атрибуты качества.

Системные риски.При рассмотрении полного набора рисков выявляются системные недостатки в архитектуре. Если не бороться с такими системными рисками, то они будут угрожать бизнес-цели проекта.

25


Architecture Tradeoff Analysis Methodфазы

Фаза Действие Участники Продолжительность

0 Подготовка Руководители команды оценки и люди влияющие на принятие решений

Проходит неформально

1 Оценка Команда оценки и люди влияющие на принятие решений

1 день

2 Оценка с руководством Команда оценки, люди влияющие на принятие решений, спонсоры проекта

2 дня

3 Оценка с клиентом Команда оценки и клиент 1 неделя

26


Architecture Tradeoff Analysis Methodшаги оценки

1. Объяснение процесса ATAM

2. Презентация бизнес составляющих проекта (главные функции, ограничения, цели, атрибуты качества).

3. Презентация архитектуры (технические ограничения, главные арх. решения, применяемые шаблоны …)

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

5. Дерево атрибутов качества, существенных для проекта.

6. Анализ архитектуры с точки зрения выявления сценариев для атрибутов качества.

7. Мозговой штурм. Цель – определение приоритетов сценариев. И определения наиболее значимых для последующего анализа.

8. Анализ архитектуры. Архитектор рассказывает как предлагаемая архитектура решает задачи поставленные в сценариях.

9. Презентация результатов: архитектурные тактики, набор приоритезированных сценариев качества, дерево атрибутов качества, риски, точки принятия компромиссных решений.

27

Проектирование программных систем. Занятие 8

Documents