Комментарии к Paul Clements at all. 'Documenting Software Architectures. Views and Beyonds'

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

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

Prologue: Software Architectures and Documentation (~50 стр.) – пролистать как журнал (пробежаться по всем заголовкам, случайным абзацам и присмотреться к тому, что показалось странным или интересным, посмотреть картинки и таблички). Подробно и детально рассказывает, что такое архитектура, кому и зачем она нужна, критерии качества и правила описания. Вводятся ключевые понятия. Стоит внимательно прочитать:

• P.2.5 The Views and Beyond “Method” (~ 1 стр.) – объясняет подход к работе с архитектурой в этой книге.
• P.3 Architecture Views (~3 стр.) – объясняет понятие “представления” и почему представление /= архитектура.
• P.4 Architecture Styles (~ 10 стр.) – объясняет понятие архитектурного стиля как активного (инвазивного) инструмента анализа системы. Является ключевым понятием.
  • Особенно внимательно: COMING TO TERMS Module, Component
• P.5 Seven Rules for Sound Documentation – основные принципы разработки архитектурной документации. В основном очевидные и понятные по заголовкам, но есть и те к которым лучше присмотреться, к примеру: Rule 6: Keep Documentation Current but Not Too Current.

Part 1 A Collection of Software Architecture Styles (~150 стр.) – долгое, подробное и нудное описание разных архитектурных стилей, которые могут комбинироваться между собой в относительно свободном виде под текущую задачу (как именно – будет позже).

• Chapter 1 Module Views (~10 стр.) – пролистать как журнал. Рассказывает о том, как работать с архитектурой в рамках модулей («строительных блоков»).
• Chapter 2 A Tour of Some Module Styles (~55 стр.) – просмотреть как журнал с картинками (внимательно прочитать все сводные таблички по каждому стилю, разобраться в схемах и примерах).
• Chapter 3 Component-and-Connector Views (~25 стр.) – пролистать как журнал. Рассказывает о том, как представить архитектуру работающей системы.
• Chapter 4 A Tour of Some Component-and-Connector Styles (~35 стр.) – пролистать как журнал с картинками.
• Сhapter 5 Allocation Views and a Tour of Some Allocation Styles (~25 стр.) – пролистать как журнал и разобраться с примерами. Рассказывает о том, как элементы системы отображаются на окружение, аппаратуру, команду разработчиков и т.д.

Part 2 Beyond Structure: Completing the Documentation (~95 стр.) – значительно более пространное (по сравнение с частью 1) описание того, что должно содержать описание архитектуры и в каком виде. Как она может принести пользу и понимание читателю.

• Chapter 6 Beyond the Basics (~35 стр.) – пролистать как журнал. Рассказывает о том, что важно описать в архитектурной документации, почему нужны разные точки зрения, почему языки описания могут (должны) меняться в процессе работы над архитектурой, почему документация не обязана быть точной.
  • 6.4 Documenting Variation Points (~7 стр.) – прочитать внимательно. Рассказывает о точках и видах вариативности архитектур и о том, как это может описываться.
  • 6.5 Documenting Architectural Decisions (~12 стр.) – прочитать внимательно. Рассказывает о том, как можно документировать архитектурные решения и предлагает шаблон для этого. Можно (нужно) утащить.
• Chapter 7 Documenting Software Interfaces (~40 стр.) – пролистать как журнал с картинками. Рассказывает о том, что такое интерфейс (с перекосами в сторону ПО) и как его можно описать / декомпозировать.
  • 7.3 A Standard Organization for Interface Documentation -> 4. Error Handling -> ADVICE (~2 стр.) – прочитать внимательно. Есть намеки на классификацию ошибок.
  • COMING TO TERMS -> Error Handling – прочитать внимательно. Рассуждение на тему обработки ошибок.
• Chapter 8 Documenting Behavior (~20 стр.) – прочитать как журнал с картинками. Повествует о том, как описывать поведение системы или ее элементов для разных потребителей и задач.
  • Table 8.1 Types of communication – посмотреть и разобраться. Описывает виды коммуникаций между элементами ПО.

Part 3 Building the Architecture Documentation (~90 стр.) – пролистать как журнал. Раздел делает попытку дать совет о том, а как, собственно, описать архитектуру используя всё обозначенное выше, что делать и почему.

• Chapter 9 Choosing the Views (~20 стр.) – пролистать как журнал с картинками. Рассказывает о том, как подобрать представления (View) для проекта, в частности дает “аспектные профили” разных ролей. Предоставляет табличный инструмент выбора.
  • Пункт Analysts (~1 стр.) – приводится список атрибутов системного уровня.
• Chapter 10 Building the Documentation Package (~40 стр.) – пролистать как журнал.
  • 10.1 Documenting a View (~15 стр.) – прочитать внимательно. Показывает, как должно быть описано представление системы (View), а также идеи как эти описания адаптировать под проект.
  • 10.2 Documentation Beyond Views (~7 стр.) – пролистать как журнал. Какую информацию не отразить в рамках представлений системы и как ее описать в документации.
  • 10.3 Documenting a Mapping to Requirements (~5 стр.) – прочитать внимательно. Место требований в архитектурной документации.
  • и другие вопросы того, как сформировать комплект документации.
• Chapter 11 Reviewing an Architecture Document (~25 стр.) – пролистать как журнал. Рассказывает о том, как делать ревизию/рецензирование архитектурной документации с возможным привлечением экспертов.
  • 11.2.2 Example Question Set for Supporting Evaluation (~3 стр.) – прочитать внимательно. Набор вопросов для рецензирования документации с точки зрения адекватности архитектуры поставленным задачам.
  • 11.2.3 Example Question Set for Supporting Development (~3 стр.) – прочитать внимательно. Набор вопросов для рецензирования документации с точки зрения адекватности для разработчиков.

Epilogue: Using Views and Beyond with Other Approaches (~30 стр.) – данная книга в некотором смысле стоит особняком по отношению к существующим инструментам документирования. В этом разделе делается попытка сопоставить описанное с существующим в области.

Appendix A UML—Unified Modeling Language
Appendix B SysML—Systems Modeling Language
Appendix C AADL—The SAE Architecture Analysis and Design Language

(~40 стр.) Рассматривает конкретные инструменты для документирования архитектуры через призму представлений и архитектурных стилей. Внимательно пролистать.