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

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

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

Правило №1

Пиши документы с точки зрения читателей.
Дейкстра (1930–2002) говорил, что стоит потратить пару часов что бы
сделать отдельно взятое предложение в документе проще.
Нужно понять, кто читатель документации и что он ждет от неё. Нужно
понимать что читатели знают.
Нужно понимать на какие вопросы отвечают определенные секции
документа. Документ должен иметь четкий план изложения
Не злоупотребляйте жаргоном, специфичным для организации или
предметной области.
Сокращения хороши для военных методичек, но не для реальных
документов.


Правило №2

Избегайте повторений.
Каждая информация должна быть записана только в одном месте. Это
упрощает использование и модифицирование документа.
Самое страшное если одна и та же информация появляется в двух
местах в разных формах, это может серьезно запутать читателя.
Используйте в документах ссылки и hyperlink
В крайнем случае можно изложить одну информацию в нескольких
вариантах, но обязательно с разных точек зрения и аккуратно описав,
зачем это сделано.


Правило №3

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

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


Правило №4

Используйте стандартную структуру документа (шаблон).
Это помогает пользователю ориентироваться в документе и упрощает
поиск нужных пунктов.
Помогает писателю планировать работу над документом.
Помогает записывать информацию сразу как она будет известна
(например мы можем заполнить вначале 3ую секцию, а потом первые
две)
Показывает, какие работы ещё осталось выполнить (например,
помеченные как TBD).
Позволяет судить о полноте документа (если шаблон документ
описывает все аспекты)


Правило №5

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


Правило №6

Поддерживайте документ актуальным (но не очень)
Документы, которые не актуальные – ни кто не использует.
Актуальные документы все любят использовать (потому что там проще
найти ответы на вопросы).
В процессе активной разработки решения часто меняются и очень
трудоемко все сразу записывать в документ. Поэтому в плане проекта,
обычно определяют точки, когда документ актуален.


Правило №7

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


документирование

ИНТЕРФЕЙСЫ


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

Элементы программного обеспечения обладают интерфейсами.
Интерфейс – это способ взаимодействия элемента с внешним миром.
Интерфейс элемента отделен от его реализации.
Элемент может иметь множество интерфейсов.
 Для поддержки различной функциональности.
 Для поддержки эволюции интерфейсов.
Элемент не только предоставляет интерфейсы но и может требовать их
для корректной работы.
Несколько внешних систем могут взаимодействовать с интерфейсом в
одно и то же время.


Guideline по документированию

Фокусируйтесь на том как интерфейс взаимодействует с окружающей
средой, а не на том как он реализован.
Интерфейс должен предоставлять только ту информацию, которую
внешние системы должны знать. Как только вы предоставляете какую-то
информацию, то сразу внешние системы начинают от неё зависеть и Вы
уже не сможете её поменять.
Помни для кого документируешь интерфейс:
 Для разработчика из соседней команды – достаточно минимума
информации.
 Для коммерческого API нужна как можно более полная информация.
Будь как можно более конкретен и точен


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

В начале процесса проектирования
 Определяется последовательность взаимодействий элементов
 Потоки данных
 Формируются сервисы
Границы модулей определены
 Определяется семантика интерфейса, его параметры, поведение.
Модуль разработан
 Описывается уточнённый синтаксис интерфейса и уточненные
детали


Из чего состоят?

Interface Identity
 Описывает идентификацию интерфейса с точки зрения языка
программирования.
 Например: OutputObject Method (InputObject parameter)
Описание ресурсов, предоставляемых интерфейсом
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 МАИ, каф 806, ППС
13

Ресурсы – что это?

 Ресурсами могут быть как операции/методы так и данные.
 Синтаксис ресурса
 Семантика ресурса
Что будет если вызвать ресурс? Как и какие данные поменяются? Как изменится поведение?
 У переменных появились новые значения(например у возвращаемого результата)
 Изменение в видимом состоянии элемента
 События, которые появились в результате использования ресурса
 Побочные эффекты
 Результат, видимый человеком (например, программа закрылась)
 Синхронное или асинхронное использование ресурса
 Ограничение на использование ресурса (параметры, состояние элемента)
 Обработка ошибок
 Неправильные параметры, внутренние ошибки, бизнес-ошибки, ошибки среды передачи
(разрывы соединения)


Ресурсы – guideline

 Описывайте только тот результат использования ресурса, который заметен
снаружи элемента.
 Попробуйте описать семантику использования интерфейса, в терминах его
использования: если положить элемент в стэк методом push то потом он доступен
методом pop
 Избегайте слов с «двойным толкованием», таких как «может». Будьте точными.
 Описывайте все предположения о параметрах (точность, диапазоны значений,
зависимости между параметрами)
 Если нужно приводить пример использования, то делайте это отдельно от
описания ресурса. Если примеры описывать рядом, то пользователь может
предположить что ресурс можно использовать только указанным способом.
 Никогда не приводите описания того как ресурс реализуется.
 Не забывайте об атрибутах качества
 Количество запросов в единицу времени, время отклика, скорость работы и
т.д.


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

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


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.


LAAM
Lightweight Architecture Alternative Assessment Method

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


LAAM

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


LAAM

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


LAAM

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


LAAM

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

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


командный метод оценки архитектуры


участники

Роль Ответственность Характеристика
Team Leader Организует мероприятие, контактирует с клиентом, убеждается Лидер, хорошо
что все потребности клиента выполнены, формирует команду. организованный, умеющий
общаться с клиентом
Evaluation Проводит мероприятие, создает сценарии, управляет выбором Хорошее понимание
Leader и приоритезацией сценариев архитектурных проблем,
умение управлять темой
дискуссии
Scenario Scribe Записывает найденные сценарии и согласует формулировки Умение выделить суть в
сценариев технических обсуждениях
Processing Создает описание процесса в электронной форме, описывает Хорошее понимание
Scribe причины возникновения сценария архитектурных проблем,
быстрая печать
Time Keeper Определяет сколько времени тратится на обсуждение Умеет прерывать дискурсии
сценариев
Process Следит за процессом в целом, делает выводы о том как Большой опыт в оценке
Observer процесс может быть улучшен архитектуры
Process Помогает идти по шагам процесса оценки архитектуры Хорошо разбирается в
Enforcer процессе оценки
Questioner Определяет важные вопросы и точки риска Разбирается в архитектуре
и требованиях спонсоров


результаты

 Краткое изложение архитектуры.
Доступной для изложения в течении одного часа.
 Формулировки бизнес-целей.
Зачастую все участники видят бизнес-цели первый раз.
 Атрибуты качества в виде перечня сценариев.
 Связь архитектурных решений с атрибутами качества.
 Набор точек «компромисов».
Обычно они связаны с решениями, которые затрагивают несколько атрибутов качества.
 Перечень рисков.
Набор архитектурных решений, которые могут повлечь негативное влияние на атрибуты
качества.
 Системные риски.
При рассмотрении полного набора рисков выявляются системные недостатки в архитектуре.
Если не бороться с такими системными рисками, то они будут угрожать бизнес-цели проекта.


фазы

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

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

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

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

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


шаги оценки

1. Объяснение процесса ATAM
2. Презентация бизнес составляющих проекта (главные функции, ограничения, цели, атрибуты
качества).
3. Презентация архитектуры (технические ограничения, главные арх. решения, применяемые
шаблоны …)
4. Определяются ключевые архитектурные подходы и анализируются командой
5. Дерево атрибутов качества, существенных для проекта.
6. Анализ архитектуры с точки зрения выявления сценариев для атрибутов качества.
7. Мозговой штурм. Цель – определение приоритетов сценариев. И определения наиболее
значимых для последующего анализа.
8. Анализ архитектуры. Архитектор рассказывает как предлагаемая архитектура решает задачи
поставленные в сценариях.
9. Презентация результатов: архитектурные тактики, набор приоритезированных сценариев
качества, дерево атрибутов качества, риски, точки принятия компромиссных решений.


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

More Related Content

Viewers also liked (12)

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

More from Dima Dzuba (18)

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