软件架构设计-05-Document

Document Architecture

Why to document software architecture?

1. 这是记录软件架构的几个很好的理由，例如：There are several good reasons for documenting software architecture such as:
   1. 交流和社交化架构设计决策 Communicating and socialising architecture design decisions
   2. 帮助理解和评估架构设计决策 Helping understand and assess architecture design decisions
   3. 刷新设计师对某些决策的记忆 Refreshing designers' memories about certain decisions
   4. 培训架构设计人员 Training people in designing architecture
   5. 支持地理位置分散的团队 Supporting geographically ditributed teams
2. 体系结构文档用于以下活动：Architecture documentation is used for several activities:
   1. 架构设计分析 Architecture design analysis.
   2. 工作分解和分配 Work breakdown and assignment.
   3. 部署后维护 Post-deployment maintenance.
3. 软件体系结构文档提供了维护和修改决策的框架 Software architecture documentation provides a framework for maintenance and modification decisions.

Challenges in documenting architecture

1. 没有普遍接受的记录软件架构的标准或方法。No universally accepted standard or method of documenting software architecture.
2. 记录大型系统的架构可能是一项耗时且重要的任务。 Documenting architecture of large-scale system can be time consuming and non-trivial task.
3. 对用于记录架构的视图的数量和性质没有达成共识 - 资源密集型活动。No consensus on the number and nature of views used to document architecture-resource intensive activity.
4. 迫在眉睫的最后期限和不断发展的架构性质不利于架构文档的流通。Looming deadlines and evolving nature of architecture are detrimental to the currency of architecture documentation.
5. 缺乏全面的符号和工具。Absence of a comprehensive notation and tooling.

What to document?

1. 许多值得记录的事情，例如：Many things worth of documenting such as:
   1. 组件接口和依赖项 Component interfaces and dependencies
   2. 子系统约束 Subsystems constraints
   3. 测试场景 Test scenarios
   4. 围绕设计决策的上下文信息 Contextual information surrounding design decisions
2. 有几个因素会影响对记录内容的决定 Several factors affect the decision of what to document:
   1. 被记录的架构的复杂性 Complexity of the architecture being documented
   2. 应用程序的寿命 Longevity of an application
   3. 基于涉众对文档的预期使用 Based on the expected use of documentation by stakeholders

7 Rules for Architecture Documentation

1. 从读者的角度撰写文档 Write documentation from the reader's point of view
2. 避免没有意义的重复 Avoid unnecessary repetition.
3. 避免模糊性 Avoid ambiguity.
4. 使用标准的文档组织方式 Use a standard organization.
5. 记录理由 Record rationale.
6. 保持文档最新但不要太最新 Keep documentation current but not too current
7. 审查文件是否适合用途 Review documentation for fitness of purpose

Views

Styles and Views

Three Categories of Styles

Views	描述	示例
Module Views	它是如何构建为一组实现单元的？How it is structured as a set of implementation units?	分解视图、使用视图、泛化视图、分层视图、领域视图、数据模型视图
Component-connector(C&C) styles	它是如何构建为一组具有运行时行为和交互的元素的？How it is structured as a set of elements that have runtime behavior and interactions?	管道-过滤器视图、客户端-服务器视图、点对点视图、面向服务视图、发布-订阅视图
Allocation style	它与环境中的非软件结构有何关系？How it relates to non-software structures in its environment?	部署视图、安装视图、工作分配视图、其他分配视图

Styles vs. Patterns

1. 架构风格是元素和关系类型的特殊化，以及关于如何使用它们的一组约束 An architecture style is a"specialization of element and relation types, together with a set of constraints on how they can be used" (Bass, Clements, and Kazman 2003)
2. 架构模式表达了软件系统的基本结构组织模式 An architecture pattern"expresses a fundamental structural organization schema for software systems"(Buschmann et al. 1996)
3. 架构模式的一个重要部分是关注问题和上下文，以及如何在该上下文中解决问题。An essential part of an architecture pattern is its focus on the problem and context as well as how to solve the problem in that context.
4. 架构风格侧重于架构方法，对特定风格何时有用或无用提供更轻量级的指导。An architecture style focuses on the architecture approach, with more lightweight guidance on when a particular style may or may not be useful.
5. 架构模式：{问题，上下文} --> 架构方法 Architecture pattern: {problem, context} --> architecture approach
6. 架构风格：架构方式 Architecture style: architecture approach
7. 风格描述通常不包括详细的问题/上下文信息；架构模式可以。A style description does not generally include detailed problem/context information; architecture patterns do.
8. 微服务知识定义了 element，和 element 通过什么方式进行交互。

Architectural Views

1. 视图是一组系统元素和它们之间关系的表示——不是所有的系统元素，而是特定类型的那些元素 A view is a representation of a set of system elements and relations among them - not all system elements, but those of a particular type.
2. 视图让我们将系统的实体划分为有趣且易于管理的系统表示 Views let us divide the system's entity into interesting and manageable representations of the system.
3. 不同的视图支持不同的目标和用户，突出不同的系统元素和关系 Different views support different goals and users, and highlight different system elements and relations
4. 不同的视图在不同程度上暴露了不同的质量属性。 Different views expose different quality attributes to different degrees.

Structural Views

Module Views

模块是提供一组连贯职责的实现单元 A module is an implementation unit that provides a coherent set of responsibility.

没有至少一个模块视图，任何软件架构的文档都不可能是完整的 It is unlikely that the documentation of any software architecture can be complete without at least one module view.

视图示例

1. 分解视图 Decomposition view
2. 使用视图 Uses view
3. 泛化视图 Generalization view
4. 分层视图 Layered view
5. 领域视图 Aspects View
6. 数据模型视图 Data model view

Summary of Module Views

Component-Connector Views

组件和连接器视图显示具有某些运行时存在的元素，例如进程、对象、客户端、服务器和数据存储（称为“组件”）。 Component-and-connector views show elements that have some runtime presence, e.g, processes, objects, clients, servers, and data stores (being termed 'components).

附件指示哪些连接器连接到哪些组件 Attachments indicate which connectors are attached to which components.

通过将连接器的端点连接到组件的端口来显示附件。 Attachment is shown by connecting the endpoints of the connector to the ports of components.

视图示例

1. 管道和过滤器视图 Pipe-and-filter view
2. 客户端-服务器视图 Client-server view
3. 点对点视图 Peer-to-peer view
4. 面向服务的架构 (SOA) 视图 Service-oriented architecture (SOA) view
5. 发布订阅视图 Publish-subscribe view
6. 共享数据视图 Shared-data view
7. 多层视图 Multi-tier view

Summary of C&C Views

Allocation Views

1. 分配视图描述了软件单元到软件开发或执行环境元素的映射 Allocation views describe the mapping of software units to elements of an environment in which the software is developed or in which it executes.
2. 分配视图的通常目标是将软件元素所需的属性与环境元素提供的属性进行比较，以确定分配是否成功 The usual goal of an allocation view is to compare the properties required by the software element with the properties provided by the environmental elements to determine whether the allocation will be successful or not.
3. 分配视图可以描绘静态或动态视图 Allocation views can depict static or dynamic views

视图实例

1. 部署视图 Deployment view
2. 安装视图 Install view
3. 工作分配视图 Work assignment view
4. 其他分配视图 Other allocation views

Summary of Allocation Views

Quality Views

1. 安全视图 Security view
2. 性能视图 Performance view
3. 可靠性视图 Reliability view
4. 通信视图 Communication View
5. 异常（错误处理）视图 Exception(error-handling) view

Documenting Views

3-Step for Choosing Views

1. 步骤 1：构建涉众/视图表 Step-1: Build a stakeholder/view table
2. 步骤 2：合并视图 Step-2: Combine views
   1. 2.1 识别上表中的边缘视图 2.1 Identify marginal views in the above table
   2. 2.2 通过关联一个视图中的元素和另一个视图中的元素，将每个边缘视图与另一个具有更强选区的视图相结合 2.2 Combine each marginal views with another view with stronger constituency by associating between elements in one view and elements in the other
3. 步骤 3：确定优先级和阶段 Step-3: Prioritize and stage
   1. 分解视图 decomposition view
   2. 80/20 原则 80/20 principle
   3. 按顺序完成所有视图？complete all views in sequence?

Stakeholder and Documentation

Stackholder-View Table

上图中每一个格子是指涉众对某一个部分的细节了解程度。

Combining Views

1. 各种 C&C 视图 Various C&C view
2. 带有 SOA 或通信进程视图的部署视图 Deployment view with either SOA or communicating- process Views
3. 分解视图和任何工作分配、实施、使用或分层视图 Decomposition view and any of work assignment, implementation, uses, or layered views

• 使用一张视图说明整个系统的部署信息

• 描述了 component 之间的关系

View Template

1. 第 1 部分：主要介绍 Section-1: The Primary Presentation
   1. 显示视图的元素和关系 shows the elements and relations of the view
   2. 通常带有一个键的图形 often graphical with a key
2. 第 2 部分：元素目录 Section-2: The Element Catalog
   1. 详细介绍了第 1 节中描述的元素。details the elements depicted in Sect.1
   2. 元素及其属性 Elements and their properties
   3. 关系及其属性 Relations and their properties
   4. 元素接口和行为 Element interfaces and behavior
3. 第 3 部分：上下文图 Section-3: Context Diagram
   1. 系统或其部分如何与其环境相关 how the system or its portion relates to its envlronment
4. 第 4 部分：可变性指南 Section-4: Variability Guide
   1. 如何在此视图中练习架构的任何变化点 how to exercise any variation points of the architecture in this view
5. 第 5 节：基本原理 Section-5: Rationale
   1. 为什么设计反映在视图中 why the design reflected in the view
   2. 提供了一个令人信服的论据，证明它是合理的。 provides a convincing argument that it is sound .

Context Diagram

Beyond (Information Beyond Views)

Documentation Beyond Views

第 1 部分：文档路线图说明文档中的信息以及在哪里可以找到它 Section-1: Documentation Roadmap tells what in formation is in the documentation and where to find it

1. 范围和总结 Scope and summary
2. 文档的组织方式 How the documentation is organized
   1. 简短的概要 short synopsis
   2. 带注释的目录 annotated table of contents
3. 查看概览 View overview
4. 利益相关者如何使用文档 How stakeholders can use the documentation

Document Control information

Mapping between Views

Documentation Package