《Documenting Software Architectures 2nd》
About the Cover xxi
Foreword to the Second Edition xxiii
Foreword to the First Edition xxv
Preface xxix
Acknowledgments xxxiii
Reader’s Guide xxxv
Prologue: Software Architectures and Documentation 1
The prologue establishes the necessary concepts and vocabulary for the
remainder of the book. It discusses how software architecture documentation
is used and why it is important. It defines the concepts that
provide the foundation of the book’s approach to documentation. It also
contains seven basic rules for sound documentation.
P.1 A Short Overview of Software Architecture 1
P.1.1 Overview 1
P.1.2 Architecture and Quality Attributes 2
Coming to Terms: What Is Software Architecture? 3
Perspectives: What’s the Difference Between Architecture and Design? 6
P.2 A Short Overview of Architecture Documentation 9
P.2.1 Why Document Software Architecture? 9
Coming to Terms: Specification, Representation, Description, Documentation 10
P.2.2 Uses and Audiences for Architecture
Documentation 12
P.2.3 Architecture Documentation and Quality
Attributes 17
P.2.4 Economics of Architecture Documentation 18
P.2.5 The Views and Beyond “Method” 19
P.2.6 Views and Beyond in an Agile Environment 20
P.2.7 Architectures That Change Faster Than You
Can Document Them 20
P.3 Architecture Views 22
Coming to Terms: A Short History of Architecture Views 23
P.4 Architecture Styles 25
P.4.1 Three Categories of Styles 29
Coming to Terms: Module, Component 29
Coming to Terms: “Architecture Style” and “Architecture Pattern” 32
P.5 Seven Rules for Sound Documentation 36
Perspectives: Beware Notations Everyone “Just Knows” 38
Perspectives: Quivering at Arrows 41
P.6 Summary Checklist 45
P.7 Discussion Questions 46
P.8 For Further Reading 47
Part I A Collection of Software Architecture Styles 49
Part I introduces the basic tools for software architecture documentation: architecture
styles. A style is a specialization of element and relationship types,
together with constraints on how they may be used. By identifying element and
relationship types, styles identify the architecture structures that architects design
to achieve the system’s quality and behavioral goals. There are three fundamental
kinds of structures: module structures, component-and-connector structures,
and allocation structures. Within each category reside a number of architecture
styles. The introduction to Part I includes a brief catalog of the styles that are
described in Chapters 1–5.
I.1 Three Categories of Styles 49
I.2 Style Guides: A Standard Organization for Explaining
a Style 50
I.3 Choosing Which Element and Relation Properties to
Document 52
I.4 Notations for Architecture Views 53
I.5 Examples 54
Chapter 1 Module Views 55
A module is an implementation unit of software that provides a coherent
unit of functionality. Modules form the basis of many standard architecture
views. This chapter defines modules and outlines the information
required for documenting module views.
1.1 Overview 55
1.2 Elements, Relations, and Properties of Module Views 56
1.2.1 Elements 56
1.2.2 Relations 57
1.2.3 Properties 57
1.3 What Module Views Are For 59
1.4 Notations for Module Views 60
1.4.1 Informal Notations 60
1.4.2 Unified Modeling Language 61
1.4.3 Dependency Structure Matrix 62
1.4.4 Entity-Relationship Diagram 62
1.5 Relation to Other Views 63
1.6 Summary Checklist 63
1.7 Discussion Questions 64
1.8 For Further Reading 64
Chapter 2 A Tour of Some Module Styles 65
This chapter introduces some common and important styles in the
module category. Each style is presented in terms of how it specializes
the overall elements and relations found in module styles.
2.1 Decomposition Style 65
2.1.1 Overview 65
2.1.2 Elements, Relations, and Properties 66
2.1.3 What the Decomposition Style Is For 67
2.1.4 Notations for the Decomposition Style 67
2.1.5 Relation to Other Styles 68
2.1.6 Examples Using the Decomposition Style 69
Coming to Terms: Subsystem 73
2.2 Uses Style 74
2.2.1 Overview 74
2.2.2 Elements, Relations, and Properties 75
2.2.3 What the Uses Style Is For 75
2.2.4 Notations for the Uses Style 76
2.2.5 Relation to Other Styles 79
2.2.6 Examples Showing the Uses Style 79
Coming to Terms: Uses 81
2.3 Generalization Style 82
2.3.1 Overview 82
2.3.2 Elements, Relations, and Properties 83
2.3.3 What the Generalization Style Is For 84
2.3.4 Notations for the Generalization Style 84
2.3.5 Relation to Other Styles 84
2.3.6 Examples Using the Generalization Style 85
2.4 Layered Style 87
2.4.1 Overview 87
2.4.2 Elements, Relations, and Properties 89
2.4.3 What the Layered Style Is For 90
2.4.4 Notations for the Layered Style 92
2.4.5 Relation to Other Styles 96
2.4.6 Examples Using the Layered Style 97
Coming to Terms: Virtual Machines 99
Perspectives: Calling Higher Layers 100
Perspectives: Using a DSM to Maintain a Layered Architecture 101
2.5 Aspects Style 104
2.5.1 Overview 104
2.5.2 Elements, Relations, and Properties 104
2.5.3 What the Aspects Style Is For 105
2.5.4 Notations for the Aspects Style 105
2.5.5 Relation to Other Styles 106
2.5.6 Examples Using the Aspects Style 106
Coming to Terms: Aspect-Oriented Programming 107
2.6 Data Model 109
2.6.1 Overview 109
2.6.2 Elements, Relations, and Properties 111
2.6.3 What the Data Model Is For 114
2.6.4 Notations for the Data Model Style 116
2.6.5 Relations to Other Styles 117
2.6.6 Examples 118
Coming to Terms: Entity 118
2.7 Summary Checklist 120
2.8 Discussion Questions 120
2.9 For Further Reading 121
Chapter 3 Component-and-Connector Views 123
Component-and-connector views represent units of execution plus the
pathways and protocols of their interaction. This chapter defines components
and connectors and describes the rules for documenting them.
3.1 Overview 123
3.2 Elements, Relations, and Properties of C&C Views 126
3.2.1 Elements 127
3.2.2 Component-and-Connector Types and
Instances 129
3.2.3 Relations 131
3.2.4 Properties 133
Perspectives: Are Complex Connectors Necessary? 135
3.3 What C&C Views Are For 136
Perspectives: Choosing Connector Abstractions 137
3.4 Notations for C&C Views 139
3.4.1 Informal Notations 139
3.4.2 Formal Notations 139
3.4.3 Semiformal Notations: UML 139
Perspectives: Data Flow and Control Flow Models 146
Contents ■ xiii
3.5 Relation to Other Kinds of Views 148
3.6 Summary Checklist 150
3.7 Discussion Questions 151
3.8 For Further Reading 152
Chapter 4 A Tour of Some Component-and-Connector Styles 155
This chapter introduces some important component-and-connector
(C&C) styles. The chapter describes how each style is a specialization of
the generic elements and relations of C&C styles, discusses what makes
each style useful, and explains how each style is documented.
4.1 An Introduction to C&C Styles 155
4.2 Data Flow Styles 157
4.2.1 Pipe-and-Filter Style 158
4.3 Call-Return Styles 161
4.3.1 Client-Server Style 162
4.3.2 Peer-to-Peer Style 166
4.3.3 Service-Oriented Architecture Style 169
4.4 Event-Based Styles 172
4.4.1 Publish-Subscribe Style 174
4.5 Repository Styles 178
4.5.1 Shared-Data Style 178
4.6 Crosscutting Issues for C&C Styles 182
4.6.1 Communicating Processes 182
4.6.2 Tiers 183
4.6.3 Dynamic Creation and Destruction 184
4.7 Summary Checklist 185
4.8 Discussion Questions 186
4.9 For Further Reading 187
Chapter 5 Allocation Views and a Tour of Some
Allocation Styles 189
Software architects are often obliged to document nonsoftware structures
and show how the software designs are mapped to the structures:
the computing environment in which their software will run, the organizational
environment in which it will be developed, and so on. This chapter
introduces the allocation view category, which is used to express the
allocation of software elements to nonsoftware structures, and three major
allocation styles.
5.1 Overview 189
5.2 Deployment Style 191
5.2.1 Overview 191
5.2.2 Elements, Relations, and Properties 192
5.2.3 What the Deployment Style Is For 194
xiv ■ Contents
5.2.4 Notation for the Deployment Style 196
5.2.5 Relation to Other Styles 197
5.3 Install Style 198
5.3.1 Overview 198
5.3.2 Elements, Relations, and Properties 199
5.3.3 What the Install Style Is For 200
5.3.4 Notations for the Install Style 200
5.3.5 Relation to Other Styles 202
5.4 Work Assignment Style 202
5.4.1 Overview 202
5.4.2 Elements, Relations, and Properties 202
5.4.3 What a Work Assignment Style Is For 203
5.4.4 Notations for the Work Assignment Style 203
5.4.5 Relation to Other Styles 204
Perspectives: Why Is a Work Assignment View Architectural? 205
5.5 Other Allocation Styles 206
Perspectives: Coordination Views 209
5.6 Summary Checklist 213
5.7 Discussion Questions 213
5.8 For Further Reading 214
Part II Beyond Structure: Completing the
Documentation 215
Part II concentrates on the rest of the information an architect should include in
architecture documentation, such as context diagrams, variation points, interfaces,
and software behavior.
Chapter 6 Beyond the Basics 217
This chapter introduces documentation approaches to handle some special
architecture issues and situations, such as breaking a view into chunks,
documenting context and variation points, and combining views.
6.1 Refinement 218
6.1.1 Decomposition Refinement 218
6.1.2 Implementation Refinement 219
6.1.3 Spectrum of Design 220
6.1.4 Style Specialization 221
6.2 Descriptive Completeness 222
6.3 Documenting Context Diagrams 225
6.3.1 Create Context Diagrams Using the
Vocabulary of the View 226
6.3.2 Content of a Context Diagram 228
6.3.3 Context Diagrams and Other Supporting
Documentation 229
6.3.4 Notations for Context Diagrams 229
Contents ■ xv
6.4 Documenting Variation Points 231
6.4.1 What Are Variation Points? 231
6.4.2 Variation Mechanisms 232
Coming to Terms: Product-Line Architectures 234
6.4.3 Dynamism and Dynamic Architectures 234
6.4.4 Documenting Variation Points 235
6.5 Documenting Architectural Decisions 239
6.5.1 Why Document Architectural Decisions? 239
6.5.2 A Template for Documenting Architectural
Decisions 239
6.5.3 Documenting Alternatives 242
6.5.4 Which Decisions to Document 242
Perspectives: “It may sound like a lot of effort to do this, but here’s how
we do it in the trenches.” 244
6.5.5 The Payback for Documenting Architectural
Decisions 245
Perspectives: From Documenting Architectures to Architecting As
Decision Making 246
Perspectives: An Ontology of Architecture Decisions 247
6.6 Combining Views 250
6.6.1 Types of Associations Between Views 251
6.6.2 Combined Views 252
6.6.3 When to Combine Views 254
6.6.4 Examples of Combined Views 255
6.7 Summary Checklist 258
6.8 Discussion Questions 259
6.9 For Further Reading 260
Chapter 7 Documenting Software Interfaces 261
The interfaces of the elements are critical parts of any architecture, and
documenting them is an important responsibility for the architect. This
chapter tells you how to specify an interface.
7.1 Overview 261
Coming to Terms: Provided vs. Required Interfaces 264
7.2 Interface Documentation 265
7.2.1 Showing the Existence of Interfaces in
Diagrams 268
7.3 A Standard Organization for Interface Documentation 271
Coming to Terms: Error Handling 277
7.4 Stakeholders of Interface Documentation 278
7.5 Conveying Syntactic Information 279
7.6 Conveying Semantic Information 280
Coming to Terms: Signature, Interface, API 280
xvi ■ Contents
7.7 Examples of Interface Documentation 281
7.7.1 Zip Component API 281
7.7.2 Interface to a SOAP Web Service 285
7.8 Summary Checklist 285
7.9 Discussion Questions 286
7.10 For Further Reading 286
Chapter 8 Documenting Behavior 289
Documenting behavior is an essential counterpoint to documenting
structure. This chapter covers the techniques and notations available for
expressing the behavior of elements, groups of elements, and the system
as a whole.
8.1 Beyond Structure 289
8.2 How to Document Behavior 290
8.2.1 Step 1: Decide What Kinds of Questions
You Need to Answer 290
8.2.2 Step 2: Determine What Types of
Information Are Available or Can Be
Constrained 291
8.2.3 Step 3: Choose a Notation 293
8.3 Notations for Documenting Behavior 295
8.3.1 Notations for Capturing Traces 295
8.3.2 Notations for Capturing Comprehensive
Models 303
8.4 Where to Document Behavior 306
8.5 Why to Document Behavior 306
8.5.1 Driving Development Activities 306
8.5.2 Analysis 307
8.6 Summary Checklist 308
8.7 Discussion Questions 309
8.8 For Further Reading 311
Part III Building the Architecture Documentation 313
Part III covers what you have to do to create and maintain the documentation
artifacts: choosing views to include, laying out and packaging the information,
and reviewing the document.
Chapter 9 Choosing the Views 315
This chapter provides guidance for selecting views, given the intended use
of an architecture: analysis, reconstruction, achieving common understanding,
the basis for deriving code, and so on.
9.1 Stakeholders and Their Documentation Needs 316
Contents ■ xvii
9.2 A Method for Choosing the Views 326
Perspectives: Listening to the Stakeholders 327
9.3 Example 329
Perspectives: How Not to Introduce an Architecture 333
9.4 Summary Checklist 335
9.5 Discussion Questions 335
9.6 For Further Reading 335
Chapter 10 Building the Documentation Package 337
This chapter explains how the documentation is organized to serve its
stakeholders. The chapter shows how the elements discussed in the
prior chapters fit together to produce usable documentation. The chapter
includes templates for architecture documentation.
10.1 Documenting a View 337
10.1.1 A Standard Organization for Documenting
a View 337
Perspectives: From Context Diagrams to a Context View 341
10.1.2 Useful Variations in the Standard Organization
for a View 344
10.1.3 Avoiding Unnecessary Repetition Across
Views or View Packets 349
10.2 Documentation Beyond Views 350
10.2.1 A Standard Organization for Documenting
Information Beyond Views 351
10.2.2 Useful Variations in the Standard Organization
for Documentation Beyond Views 356
10.3 Documenting a Mapping to Requirements 357
Perspectives: A Mapping to Requirements: You Might Already Have It 362
10.4 Packaging the Architecture Documentation 362
10.4.1 Packaging Schemes 362
10.4.2 Online Documentation, Hypertext, and Wikis 365
Coming to Terms: Wiki 366
10.4.3 Configuration Management 368
10.4.4 Follow a Release Strategy 368
Perspectives: Presentation Is Also Important 369
Perspectives: Tooling Requirements 370
10.5 Summary Checklist 372
10.6 For Further Reading 373
Chapter 11 Reviewing an Architecture Document 375
This chapter describes a step-by-step approach for conducting a structured
review of an architecture document, and it includes a large selection
of review questions.
11.1 Steps of the Procedure 376
Coming to Terms: Active Design Reviews 380
xviii ■ Contents
11.2 Sample Question Sets for Reviewing the
Architecture Document 382
11.2.1 Example Question Set for Capturing the
Right Stakeholders and Concerns 385
11.2.2 Example Question Set for Supporting
Evaluation 386
11.2.3 Example Question Set for Supporting
Development 389
11.2.4 Example Question Set for Reviewing for
Conformance to ISO/IEC 42010 391
11.3 An Example of Constructing and Conducting a Review 393
11.4 Summary Checklist 395
11.5 Discussion Questions 396
11.6 For Further Reading 396
Epilogue: Using Views and Beyond with Other Approaches 399
The epilogue compares the “Views and Beyond” approach to other documentation
approaches. It ties related work to the prescriptions given in
this book.
E.1 ISO/IEC 42010, née ANSI/IEEE Std 1471-2000 400
E.1.1 Overview 400
E.1.2 42010 and Views and Beyond 404
E.2 Rational Unified Process/Kruchten 4+1 406
E.2.1 RUP/4+1 and Views and Beyond 406
E.3 Using the Rozanski and Woods Viewpoint Set 408
Coming to Terms: Architecture Perspectives 410
E.3.1 Rozanski and Woods Viewpoints and Views
and Beyond 411
E.4 Documenting Architecture in an Agile Development
Project 414
E.4.1 Overview 414
E.4.2 Agile Development and Views and Beyond 415
E.5 U.S. Department of Defense Architecture Framework 419
E.5.1 Overview of DoDAF 419
E.5.2 DoDAF and Software Architecture 421
E.5.3 DoDAF and Views and Beyond 421
E.5.4 A Strategy to Use DoDAF to Document
Software Architecture 426
E.6 Where Architecture Documentation Ends 428
E.7 A Final Word 429
E.8 For Further Reading 429
Contents ■ xix
Appendix A UML—Unified Modeling Language 431
This appendix gives an overview of the Unified Modeling Language and
tells how it should be used to document the architecture constructs
described in this book.
A.1 Introduction 431
A.2 Documenting a Module View 433
A.2.1 Decomposition Style 433
A.2.2 Uses Style 433
A.2.3 Generalization Style 434
A.2.4 Layered Style 434
A.2.5 Aspects Style 434
A.2.6 Data Model Style 435
Perspectives: UML Class Diagrams: Too Much, Too Little 436
A.3 Documenting a Component-and-Connector View 438
A.4 Documenting an Allocation View 443
A.4.1 Deployment Style 443
A.4.2 Install and Implementation Styles 445
A.4.3 Work Assignment Style 446
A.5 Documenting Behavior 449
A.5.1 Activity Diagram 450
A.5.2 Sequence Diagram 450
A.5.3 Communication Diagram 453
A.5.4 Timing Diagram 454
A.5.5 Interaction Overview Diagram 455
A.5.6 State Machine Diagram 457
A.5.7 Use Case Diagram 458
A.6 Documenting Interfaces 460
Perspectives: UML Tools 461
Appendix B SysML—Systems Modeling Language 465
The Systems Modeling Language (SysML) is a general-purpose systems
modeling language intended to support a broad range of analysis and
design activities for systems engineering applications. This appendix
gives a short overview of using SysML to represent an architecture.
B.1 Architecture Documentation 466
B.2 Requirements 466
B.3 Documenting a Module View 468
B.4 Documenting a Component-and-Connector View 469
B.5 Documenting an Allocation View 470
B.6 Documenting Behavior 471
B.7 Documenting Interfaces 472
B.8 Summary 472
xx ■ Contents
Appendix C AADL—The SAE Architecture Analysis and
Design Language 473
The Architecture Analysis and Design Language (AADL) provides a textual
and graphical language to represent the runtime architecture of software
systems as a component-based model in terms of tasks and their
interactions, the hardware platform on which the system executes, and the
physical environment with which it interfaces. This appendix summarizes
AADL and briefly describes how it can be used to document architectures.
C.1 Introduction 473
C.2 Documenting a Module Style 475
C.3 Documenting a Component-and-Connector View 478
C.4 Documenting a Deployment View 481
C.5 Documenting Behavior 482
C.6 Documenting Interfaces 484
C.7 Summary 484
Acronyms 487
Glossary 491
References 497
About the Authors 509
About the Contributors 513
Index 517