Documenting Software Architectures
Views and Beyond
Published on 8. October 2002
Book
Hardback
560 pages
978-0-201-70372-6 (ISBN)
Description
Architecture is crucial to the success of any large software system -- but even a superb architecture will fail if it isn't communicated well. Now, there's a language- and notation-independent guide to capturing architecture so it can be used successfully by every analyst, software designer, and developer. The authors review the diverse goals and uses of software architecture documentation, providing documentation strategies for several common scenarios. They identify the basic unit of software architecture documentation: the viewtype, which specifies the type of information to be provided in an architectural view. For each viewtype -- Modules, Component-and-Connectors, and Allocation -- they offer detailed guidance on documenting what really matters. Next, they demonstrate how to package architecture documentation in coherent, usable form: augmenting architectural views with documentation of interfaces and behavior; accounting for architectural variability and dynamic systems; and more.
More details
Language
English
Place of publication
Boston
United States
Publishing group
Pearson Education (US)
Target group
College/higher education
Dimensions
Height: 241 mm
Width: 242 mm
Thickness: 31 mm
Weight
861 gr
ISBN-13
978-0-201-70372-6 (9780201703726)
Copyright in bibliographic data and cover images is held by Nielsen Book Services Limited or by the publishers or by their respective licensors: all rights reserved.
Schweitzer Classification
Other editions
New editions
Paul Clements | Felix Bachmann | Len Bass
Documenting Software Architectures: Views and Beyond
Views and Beyond
Book
10/2010
2nd Edition
Addison Wesley
€76.49
Shipment within 10-20 days
Persons
Paul Clements is a senior member of the technical staff at the SEI, where he works on software architecture and product line engineering. He is the author of five books and more than three dozen papers on these and other topics.
Len Bass is a senior member of the technical staff at the Software Engineering Institute (SEI). He has written or edited five books and numerous papers on software engineering and other topics. He has extensive experience in architecting real-world development projects.
Robert L. Nord, a member of the software architecture program at SCR, designs and evaluates software architectures for large-scale industrial systems. Dr. Nord, currently the Siemens industrial resident affiliate at the Software Engineering Institute (SEI) in Pittsburgh, is working on methods for architecture trade-off analysis and product-line practices. His other interests include transitioning software design practices, improving architecture practices using software architecture improvement groups, and architecture-based development.
0201703726AB01162003
Len Bass is a senior member of the technical staff at the Software Engineering Institute (SEI). He has written or edited five books and numerous papers on software engineering and other topics. He has extensive experience in architecting real-world development projects.
Robert L. Nord, a member of the software architecture program at SCR, designs and evaluates software architectures for large-scale industrial systems. Dr. Nord, currently the Siemens industrial resident affiliate at the Software Engineering Institute (SEI) in Pittsburgh, is working on methods for architecture trade-off analysis and product-line practices. His other interests include transitioning software design practices, improving architecture practices using software architecture improvement groups, and architecture-based development.
0201703726AB01162003
Content
About the Cover.
Foreword.
Preface.
Acknowledgments.
Reader's Guide.
Prologue: Software Architectures and Documentation.
The Role of Architecture.
Coming to Terms: Software Architecture.
Perspectives: What's the Difference Between Architecture and Design?
Coming to Terms: Documentation, Description, Representation, Specification.
Uses of Architecture Documentation.
Interfaces.
Views.
Coming to Terms: Architectural Views.
Viewtypes and Styles.
Viewtypes.
Styles.
Summary: Viewtypes, Styles, and Views.
Coming to Terms: Module, Component.
Seven Rules for Sound Documentation.
Rule 1: Write Documentation from the Reader's Point of View.
Rule 2: Avoid Unnecessary Repetition.
Rule 3: Avoid Ambiguity.
Rule 4: Use a Standard Organization.
Rule 5: Record Rationale.
Rule 6: Keep Documentation Current But Not Too Current.
Rule 7: Review Documentation for Fitness of Purpose.
Perspectives: Quivering at Arrows.
Summary Checklist.
Discussion Questions.
For Further Reading.
I. SOFTWARE ARCHITECTURE VIEWTYPES AND STYLES.
Viewtypes and Style Catalog.
Module Viewtype.
Component-and-Connector Viewtype.
Allocation Viewtype.
Style Guides: A Standard Organization for Documenting a Style.
1. The Module Viewtype.
Overview.
Elements, Relations, and Properties of the Module Viewtype.
Elements.
Relations.
Properties.
Coming to Terms: Substitutability.
What the Module Viewtype Is For and What It's Not For.
Notations for the Module Viewtype.
Informal Notations.
UML.
Relation to Other Viewtypes.
Summary Checklist.
Discussion Questions.
For Further Reading.
2. Styles of the Module Viewtype.
Decomposition Style.
Overview.
Elements, Relations, and Properties.
What the Decomposition Style Is For and What It's Not For.
Notations for the Decomposition Style.
Relation to Other Styles.
Examples of the Decomposition Style.
Coming to Terms: Subsystem 622.2 Uses Style.
Overview.
Elements, Relations, and Properties.
What the Uses Style Is For and What It's Not For.
Notations for the Uses Style.
Relation to Other Styles.
Example of the Uses Style.
Coming to Terms: Uses 682.3 Generalization Style.
Overview.
Elements, Relations, and Properties.
What the Generalization Style Is For and What It's Not For.
Notations for the Generalization Style.
Relation to Other Styles.
Coming to Terms: Generalization.
Examples of the Generalization Style.
Layered Style.
Overview.
Elements, Relations, and Properties.
What the Layered Style Is For and What It's Not For.
Notations for the Layered Style.
Relation to Other Styles.
Examples of the Layered Style.
Coming to Terms: Virtual Machines.
Perspectives: Upwardly Mobile Software.
Perspectives: Levels of Distraction.
Perspectives: UML Class Diagrams: Too Much, Too Little.
Summary Checklist.
Discussion Questions.
For Further Reading.
3 The Component-and-Connector Viewtype.
Overview.
Elements, Relations, and Properties of the C&C Viewtype.
Elements.
Relations.
Properties.
Perspectives: Are Connectors Necessary?
Perspectives: Choosing Connector Abstractions.
What the C&C Viewtype Is For and What It's Not For.
Perspectives: Data Flow and Control Flow Projections.
Notations for the C&C Viewtype.
Relation to Other Viewtypes.
Summary Checklist.
Discussion Questions.
For Further Reading.
4. Styles of the Component-and-Connector Viewtype.
The Pipe-and-Filter Style.
Overview.
Elements, Relations, and Properties.
What the Pipe-and-Filter Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Pipe-and-Filter Style.
Shared-Data Style.
Overview.
Elements, Relations, and Properties.
What the Shared-Data Style Is For and What It's Not For.
Relation to Other Styles.
Example of the Shared-Data Style.
Publish-Subscribe Style.
Overview.
Elements, Relations, and Properties.
What the Publish-Subscribe Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Publish-Subscribe Style.
Client-Server Style.
Overview.
Elements, Relations, and Properties.
What the Client-Server Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Client-Server Style.
Peer-to-Peer Style.
Overview.
Elements, Relations, and Properties.
What the Peer-to-Peer Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Peer-to-Peer Style.
Communicating-Processes Style.
Overview.
Elements, Relations, and Properties.
What the Communicating-Processes Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Communicating-Processes Style.
Notations for C&C Styles.
Informal Notations.
Formal Notations.
Perspectives: Using Classes to Represent Component Types and Instances.
Coming to Terms: Components Versus UML Components.
Summary Checklist.
Discussion Questions.
For Further Reading.
5. The Allocation Viewtype and Styles.
Overview.
Elements, Relations, and Properties of the Allocation Viewtype.
Deployment Style.
Overview.
Elements, Relations, and Properties.
What the Deployment Style Is For and What It's Not For.
Notation for the Deployment Style.
Relation to Other Styles.
Examples of the Deployment Style.
Implementation Style.
Overview.
Elements, Relations, and Properties.
What the Implementation Style Is For and What It's Not For.
Notation for the Implementation Style.
Relation to Other Styles.
Example of the Implementation Style.
Work Assignment Style.
Elements, Relations, and Properties.
What the Work Assignment Style Is For and What It's Not For.
Notations for the Work Assignment Style.
Relation to Other Styles.
Example of the Work Assignment Style.
Summary Checklist.
Discussion Questions.
For Further Reading.
II. SOFTWARE ARCHITECTURE DOCUMENTATION IN PRACTICE.
6. Advanced Concepts.
Chunking Information: View Packets, Refinement, and Descriptive Completeness.
View Packets.
Refinement.
Descriptive Completeness.
Using Context Diagrams.
Top-Level Context Diagrams.
Content of a Context Diagram.
Context Diagrams and Other Supporting Documentation.
Notations for Context Diagrams.
Example of a Context Diagram.
Combined Views.
When to Combine Views.
Types of Mapping.
Elements, Relations, and Properties.
Documenting Combined Views.
Examples of Combined Views.
Other Examples.
Documenting Variability and Dynamism.
Variability.
Dynamism.
Recording the Information.
Notations for Variability and Dynamism.
Perspectives: What Time Is It?
Creating and Documenting a New Style.
Coming to Terms: Styles, Patterns.
Summary Checklist.
Discussion Questions.
For Further Reading.
7. Documenting Software Interfaces.
Overview.
Interface Specifications.
A Standard Organization for Interface Documentation.
Coming to Terms: Exceptions and Error Handling.
Stakeholders of Interface Documentation.
Notation for Interface Documentation.
Showing the Existence of Interfaces.
Conveying Syntactic Information.
Conveying Semantic Information.
Summary.
Perspectives: Multiple Interfaces.
Coming to Terms: Signature, Interface, API.
Examples of Interface Documentation.
SCR-Style Interface.
IDL.
Custom Notation.
XML.
Summary Checklist.
Discussion Questions.
For Further Reading.
8. Documenting Behavior.
Beyond Structure.
Where to Document Behavior.
Why to Document Behavior.
System Analysis.
Driving Development Activities.
What to Document.
Types of Communication.
Constraints on Ordering.
Clock-Triggered Stimulation.
How to Document Behavior: Notations and Languages.
Traces.
Static Models.
Summary Checklist.
Discussion Questions.
For Further Reading.
9. Choosing the Views.
Stakeholders and Their Documentation Needs.
Perspectives: Architecture Trade-off Analysis Method.
Making the Choice.
Two Examples.
A Small Project: A-7E.
A Large Project: ECS.
Summary Checklist.
Discussion Questions.
For Further Reading.
10. Building the Documentation Package.
One Document or Several?
Perspectives: What the Meaning of "Is" Is.
Documenting a View.
Perspectives: Presentation Is Also Important.
Documentation Beyond Views.
How the Documentation Is Organized to Serve a Stakeholder.
What the Architecture Is.
Why the Architecture Is the Way It Is: Background, Design Constraints, and Rationale.
Perspectives: Global Analysis.
Validating Software Architecture Documentation.
Perspectives: A Glossary Would Have Helped.
Summary Checklist.
Discussion Questions.
For Further Reading.
11. Other Views and Beyond.
Overview.
Rational Unified Process/Kruchten 4+1.
UML.
Class and Object Diagrams.
Component Diagrams.
Deployment Diagrams.
Behavioral Diagrams.
Siemens Four Views.
Global Analysis.
Conceptual Architecture View.
Module Architecture View.
Execution Architecture View.
Code Architecture View.
Summary.
C4ISR Architecture Framework.
Common Architectural Views of the C4ISR Framework.
Common Products.
ANSI/IEEE-1471-2000.
Data Flow and Control Flow.
Data Flow Views.
Control Flow Views.
Perspectives: You're All Just Guessing!
RM-ODP.
Where Architecture Documentation Ends.
Architecture Description Languages.
Commercial Components.
Hypertext Documentation.
Configuration Management.
A Final Word.
For Further Reading.
Appendix A: Excerpts from a Software Architecture Documentation Package.
Volume I: ECS Software Architecture Documentation Beyond Views.
Volume II: ECS Software Architecture Views.
Glossary.
References.
Index. 0201703726T08302002
Foreword.
Preface.
Acknowledgments.
Reader's Guide.
Prologue: Software Architectures and Documentation.
The Role of Architecture.
Coming to Terms: Software Architecture.
Perspectives: What's the Difference Between Architecture and Design?
Coming to Terms: Documentation, Description, Representation, Specification.
Uses of Architecture Documentation.
Interfaces.
Views.
Coming to Terms: Architectural Views.
Viewtypes and Styles.
Viewtypes.
Styles.
Summary: Viewtypes, Styles, and Views.
Coming to Terms: Module, Component.
Seven Rules for Sound Documentation.
Rule 1: Write Documentation from the Reader's Point of View.
Rule 2: Avoid Unnecessary Repetition.
Rule 3: Avoid Ambiguity.
Rule 4: Use a Standard Organization.
Rule 5: Record Rationale.
Rule 6: Keep Documentation Current But Not Too Current.
Rule 7: Review Documentation for Fitness of Purpose.
Perspectives: Quivering at Arrows.
Summary Checklist.
Discussion Questions.
For Further Reading.
I. SOFTWARE ARCHITECTURE VIEWTYPES AND STYLES.
Viewtypes and Style Catalog.
Module Viewtype.
Component-and-Connector Viewtype.
Allocation Viewtype.
Style Guides: A Standard Organization for Documenting a Style.
1. The Module Viewtype.
Overview.
Elements, Relations, and Properties of the Module Viewtype.
Elements.
Relations.
Properties.
Coming to Terms: Substitutability.
What the Module Viewtype Is For and What It's Not For.
Notations for the Module Viewtype.
Informal Notations.
UML.
Relation to Other Viewtypes.
Summary Checklist.
Discussion Questions.
For Further Reading.
2. Styles of the Module Viewtype.
Decomposition Style.
Overview.
Elements, Relations, and Properties.
What the Decomposition Style Is For and What It's Not For.
Notations for the Decomposition Style.
Relation to Other Styles.
Examples of the Decomposition Style.
Coming to Terms: Subsystem 622.2 Uses Style.
Overview.
Elements, Relations, and Properties.
What the Uses Style Is For and What It's Not For.
Notations for the Uses Style.
Relation to Other Styles.
Example of the Uses Style.
Coming to Terms: Uses 682.3 Generalization Style.
Overview.
Elements, Relations, and Properties.
What the Generalization Style Is For and What It's Not For.
Notations for the Generalization Style.
Relation to Other Styles.
Coming to Terms: Generalization.
Examples of the Generalization Style.
Layered Style.
Overview.
Elements, Relations, and Properties.
What the Layered Style Is For and What It's Not For.
Notations for the Layered Style.
Relation to Other Styles.
Examples of the Layered Style.
Coming to Terms: Virtual Machines.
Perspectives: Upwardly Mobile Software.
Perspectives: Levels of Distraction.
Perspectives: UML Class Diagrams: Too Much, Too Little.
Summary Checklist.
Discussion Questions.
For Further Reading.
3 The Component-and-Connector Viewtype.
Overview.
Elements, Relations, and Properties of the C&C Viewtype.
Elements.
Relations.
Properties.
Perspectives: Are Connectors Necessary?
Perspectives: Choosing Connector Abstractions.
What the C&C Viewtype Is For and What It's Not For.
Perspectives: Data Flow and Control Flow Projections.
Notations for the C&C Viewtype.
Relation to Other Viewtypes.
Summary Checklist.
Discussion Questions.
For Further Reading.
4. Styles of the Component-and-Connector Viewtype.
The Pipe-and-Filter Style.
Overview.
Elements, Relations, and Properties.
What the Pipe-and-Filter Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Pipe-and-Filter Style.
Shared-Data Style.
Overview.
Elements, Relations, and Properties.
What the Shared-Data Style Is For and What It's Not For.
Relation to Other Styles.
Example of the Shared-Data Style.
Publish-Subscribe Style.
Overview.
Elements, Relations, and Properties.
What the Publish-Subscribe Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Publish-Subscribe Style.
Client-Server Style.
Overview.
Elements, Relations, and Properties.
What the Client-Server Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Client-Server Style.
Peer-to-Peer Style.
Overview.
Elements, Relations, and Properties.
What the Peer-to-Peer Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Peer-to-Peer Style.
Communicating-Processes Style.
Overview.
Elements, Relations, and Properties.
What the Communicating-Processes Style Is For and What It's Not For.
Relation to Other Styles.
Examples of the Communicating-Processes Style.
Notations for C&C Styles.
Informal Notations.
Formal Notations.
Perspectives: Using Classes to Represent Component Types and Instances.
Coming to Terms: Components Versus UML Components.
Summary Checklist.
Discussion Questions.
For Further Reading.
5. The Allocation Viewtype and Styles.
Overview.
Elements, Relations, and Properties of the Allocation Viewtype.
Deployment Style.
Overview.
Elements, Relations, and Properties.
What the Deployment Style Is For and What It's Not For.
Notation for the Deployment Style.
Relation to Other Styles.
Examples of the Deployment Style.
Implementation Style.
Overview.
Elements, Relations, and Properties.
What the Implementation Style Is For and What It's Not For.
Notation for the Implementation Style.
Relation to Other Styles.
Example of the Implementation Style.
Work Assignment Style.
Elements, Relations, and Properties.
What the Work Assignment Style Is For and What It's Not For.
Notations for the Work Assignment Style.
Relation to Other Styles.
Example of the Work Assignment Style.
Summary Checklist.
Discussion Questions.
For Further Reading.
II. SOFTWARE ARCHITECTURE DOCUMENTATION IN PRACTICE.
6. Advanced Concepts.
Chunking Information: View Packets, Refinement, and Descriptive Completeness.
View Packets.
Refinement.
Descriptive Completeness.
Using Context Diagrams.
Top-Level Context Diagrams.
Content of a Context Diagram.
Context Diagrams and Other Supporting Documentation.
Notations for Context Diagrams.
Example of a Context Diagram.
Combined Views.
When to Combine Views.
Types of Mapping.
Elements, Relations, and Properties.
Documenting Combined Views.
Examples of Combined Views.
Other Examples.
Documenting Variability and Dynamism.
Variability.
Dynamism.
Recording the Information.
Notations for Variability and Dynamism.
Perspectives: What Time Is It?
Creating and Documenting a New Style.
Coming to Terms: Styles, Patterns.
Summary Checklist.
Discussion Questions.
For Further Reading.
7. Documenting Software Interfaces.
Overview.
Interface Specifications.
A Standard Organization for Interface Documentation.
Coming to Terms: Exceptions and Error Handling.
Stakeholders of Interface Documentation.
Notation for Interface Documentation.
Showing the Existence of Interfaces.
Conveying Syntactic Information.
Conveying Semantic Information.
Summary.
Perspectives: Multiple Interfaces.
Coming to Terms: Signature, Interface, API.
Examples of Interface Documentation.
SCR-Style Interface.
IDL.
Custom Notation.
XML.
Summary Checklist.
Discussion Questions.
For Further Reading.
8. Documenting Behavior.
Beyond Structure.
Where to Document Behavior.
Why to Document Behavior.
System Analysis.
Driving Development Activities.
What to Document.
Types of Communication.
Constraints on Ordering.
Clock-Triggered Stimulation.
How to Document Behavior: Notations and Languages.
Traces.
Static Models.
Summary Checklist.
Discussion Questions.
For Further Reading.
9. Choosing the Views.
Stakeholders and Their Documentation Needs.
Perspectives: Architecture Trade-off Analysis Method.
Making the Choice.
Two Examples.
A Small Project: A-7E.
A Large Project: ECS.
Summary Checklist.
Discussion Questions.
For Further Reading.
10. Building the Documentation Package.
One Document or Several?
Perspectives: What the Meaning of "Is" Is.
Documenting a View.
Perspectives: Presentation Is Also Important.
Documentation Beyond Views.
How the Documentation Is Organized to Serve a Stakeholder.
What the Architecture Is.
Why the Architecture Is the Way It Is: Background, Design Constraints, and Rationale.
Perspectives: Global Analysis.
Validating Software Architecture Documentation.
Perspectives: A Glossary Would Have Helped.
Summary Checklist.
Discussion Questions.
For Further Reading.
11. Other Views and Beyond.
Overview.
Rational Unified Process/Kruchten 4+1.
UML.
Class and Object Diagrams.
Component Diagrams.
Deployment Diagrams.
Behavioral Diagrams.
Siemens Four Views.
Global Analysis.
Conceptual Architecture View.
Module Architecture View.
Execution Architecture View.
Code Architecture View.
Summary.
C4ISR Architecture Framework.
Common Architectural Views of the C4ISR Framework.
Common Products.
ANSI/IEEE-1471-2000.
Data Flow and Control Flow.
Data Flow Views.
Control Flow Views.
Perspectives: You're All Just Guessing!
RM-ODP.
Where Architecture Documentation Ends.
Architecture Description Languages.
Commercial Components.
Hypertext Documentation.
Configuration Management.
A Final Word.
For Further Reading.
Appendix A: Excerpts from a Software Architecture Documentation Package.
Volume I: ECS Software Architecture Documentation Beyond Views.
Volume II: ECS Software Architecture Views.
Glossary.
References.
Index. 0201703726T08302002