Documenting Software Architectures
Views and Beyond, Portable Documents
2nd Edition
Published on 20. September 2010
591 pages
978-0-13-248858-7 (ISBN)
Description
Software architecture-the conceptual glue that holds every phase of a project together for its many stakeholders-is widely recognized as a critical element in modern software development. Practitioners have increasingly discovered that close attention to a software system's architecture pays valuable dividends. Without an architecture that is appropriate for the problem being solved, a project will stumble along or, most likely, fail. Even with a superb architecture, if that architecture is not well understood or well communicated the project is unlikely to succeed.
Documenting Software Architectures, Second Edition, provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form. Drawing on their extensive experience, the authors first help you decide what information to document, and then, with guidelines and examples (in various notations, including UML), show you how to express an architecture so that others can successfully build, use, and maintain a system from it. The book features rules for sound documentation, the goals and strategies of documentation, architectural views and styles, documentation for software interfaces and software behavior, and templates for capturing and organizing information to generate a coherent package. New and improved in this second edition:
Coverage of architectural styles such as service-oriented architectures, multi-tier architectures, and data models
Guidance for documentation in an Agile development environment
Deeper treatment of documentation of rationale, reflecting best industrial practices
Improved templates, reflecting years of use and feedback, and more documentation layout options
A new, comprehensive example (available online), featuring documentation of a Web-based service-oriented system
Reference guides for three important architecture documentation languages: UML, AADL, and SySML
Documenting Software Architectures, Second Edition, provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form. Drawing on their extensive experience, the authors first help you decide what information to document, and then, with guidelines and examples (in various notations, including UML), show you how to express an architecture so that others can successfully build, use, and maintain a system from it. The book features rules for sound documentation, the goals and strategies of documentation, architectural views and styles, documentation for software interfaces and software behavior, and templates for capturing and organizing information to generate a coherent package. New and improved in this second edition:
Coverage of architectural styles such as service-oriented architectures, multi-tier architectures, and data models
Guidance for documentation in an Agile development environment
Deeper treatment of documentation of rationale, reflecting best industrial practices
Improved templates, reflecting years of use and feedback, and more documentation layout options
A new, comprehensive example (available online), featuring documentation of a Web-based service-oriented system
Reference guides for three important architecture documentation languages: UML, AADL, and SySML
More details
Edition
2nd edition
Language
English
Place of publication
Boston
United States
Publishing group
Pearson Education (US)
Target group
Professional and scholarly
File size
8,44 MB
ISBN-13
978-0-13-248858-7 (9780132488587)
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
Additional 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 Carnegie Mellon Software Engineering Institute (SEI), where he has worked since 1994 leading or coleading projects in software product-line engineering and software architecture documentation and analysis. Besides this one, Clements is the coauthor of two other practitioner-oriented books about software architecture: Software Architecture in Practice (Addison-Wesley, 1998; Second Edition 2003) and Evaluating Software Architectures: Methods and Case Studies (Addison-Wesley, 2001). He also cowrote Software Product Lines: Practices and Patterns (Addison-Wesley, 2001) and was coauthor and editor of Constructing Superior Software (Sams, 1999). In addition, Clements has authored dozens of papers in software engineering, reflecting his longstanding interest in the design and specification of challenging software systems. In 2005 and 2006 he spent a year as a visiting faculty member at the Indian Institute of Technology in Mumbai. He received a Ph.D. in computer sciences from the University of Texas at Austin in 1994. He is a founding member of the IFIP Working Group on Software Architecture (WG2.10).
Felix Bachmann is a Senior Member of the Technical Staff at the SEI, working in the Architecture Centric Engineering Initiative. He is coauthor of the Attribute-Driven Design Method, a contributor to and instructor for the ATAM Evaluator Training course, and a contributor to the book Software Architecture in Practice, Second Edition. Before joining the SEI, he was a software engineer at Robert Bosch GmbH in corporate research, where he worked with software development departments to address the issues of software engineering in small and large embedded systems.
Len Bass is a Senior Member of the Technical Staff at the SEI. He has coauthored two award-winning books in software architecture as well as several other books and numerous papers in a wide variety of areas of computer science and software engineering. He has been a keynote speaker or a distinguished lecturer on six continents. He is currently working on applying the concepts of ultra-large-scale systems to the smart grid. He has been involved in the development of numerous different production or research software systems, ranging from operating systems to database management systems to automotive systems. He is a member of the IFIP Working Group on Software Architecture (WG2.10).
David Garlan is a Professor of Computer Science and Director of Software Engineering Professional Programs in the School of Computer Science at Carnegie Mellon University (CMU). He received his Ph.D. from CMU in 1987 and worked as a software architect in industry between 1987 and 1990. His interests include software architecture, self-adaptive systems, formal methods, and cyber-physical systems. He is considered to be one of the founders of the field of software architecture and, in particular, formal representation and analysis of architectural designs. In 2005 he received a Stevens Award Citation for fundamental contributions to the development and understanding of software architecture as a discipline in software engineering.
James Ivers is a Senior Member of the Technical Staff at the SEI, where he works in the areas of software architecture and program analysis. He received a Master of Software Engineering from CMU in 1996 and has worked for and with a variety of development organizations, from start-up to multinational corporations. He has written numerous papers, contributed to the development of an international standard for distributed simulations, and has recently been working in a public-private collaboration to draft security recommendations for the smart grid.
Reed Little is a Senior Member of the Technical Staff at the SEI. He applies more than 35 years of experience in computer simulation, software architecture, software product lines, man-machine interface, artificial intelligence, and programming language design to various aspects of applied research and hands-on customer assistance for large (more than three million lines of code) software systems.
Paulo Merson has more than 20 years of software development experience. He works for the SEI in the areas of software architecture, service-oriented architecture, and aspect-oriented software development. He is also a practicing software architect in industry. One of his assignments at the SEI is to teach a two-day course in "Documenting Software Architectures" for industry and government practitioners. His speaking experience also includes tutorials at various conferences, such as SD Best Practices, Dr. Dobb's Architecture & Design World, and JavaOne. Prior to joining the SEI, he was a Java EE consultant. Paulo holds a B.Sc. in Computer Science from University of Brasilia, and a Master of Software Engineering from CMU.
Robert Nord is a Senior Member of the Technical Staff in the Research, Technology, and System Solutions Program at the SEI, where he works to develop and communicate effective methods and practices for software architecture. He is coauthor of the practitioner-oriented book Applied Software Architecture (Addison-Wesley, 2000) and lectures on architecture-centric approaches. He is a member of the IFIP Working Group on Software Architecture (WG2.10).
Judith Stafford is a Senior Lecturer at Tufts University and a Visiting Scientist at the SEI. Before joining the faculty at Tufts University, she was a Senior Member of the Technical Staff at the SEI in the Product Lines Systems Program, working in the Software Architecture Technologies Initiative. She has authored several book chapters on the topic of software architecture analysis, software architecture support for software component composition, and software architecture documentation. Stafford has been an organizer and program committee member for several conferences and workshops, and a guest editor on several leading software engineering journal special issues. She received her Ph.D. and M.S. degrees in Computer Science from the University of Colorado at Boulder. She is a member of the IEEE Computer Society, ACM SIGSOFT and SIGPLAN, and the IFIP Working Group on Software Architecture (WG2.10).
Felix Bachmann is a Senior Member of the Technical Staff at the SEI, working in the Architecture Centric Engineering Initiative. He is coauthor of the Attribute-Driven Design Method, a contributor to and instructor for the ATAM Evaluator Training course, and a contributor to the book Software Architecture in Practice, Second Edition. Before joining the SEI, he was a software engineer at Robert Bosch GmbH in corporate research, where he worked with software development departments to address the issues of software engineering in small and large embedded systems.
Len Bass is a Senior Member of the Technical Staff at the SEI. He has coauthored two award-winning books in software architecture as well as several other books and numerous papers in a wide variety of areas of computer science and software engineering. He has been a keynote speaker or a distinguished lecturer on six continents. He is currently working on applying the concepts of ultra-large-scale systems to the smart grid. He has been involved in the development of numerous different production or research software systems, ranging from operating systems to database management systems to automotive systems. He is a member of the IFIP Working Group on Software Architecture (WG2.10).
David Garlan is a Professor of Computer Science and Director of Software Engineering Professional Programs in the School of Computer Science at Carnegie Mellon University (CMU). He received his Ph.D. from CMU in 1987 and worked as a software architect in industry between 1987 and 1990. His interests include software architecture, self-adaptive systems, formal methods, and cyber-physical systems. He is considered to be one of the founders of the field of software architecture and, in particular, formal representation and analysis of architectural designs. In 2005 he received a Stevens Award Citation for fundamental contributions to the development and understanding of software architecture as a discipline in software engineering.
James Ivers is a Senior Member of the Technical Staff at the SEI, where he works in the areas of software architecture and program analysis. He received a Master of Software Engineering from CMU in 1996 and has worked for and with a variety of development organizations, from start-up to multinational corporations. He has written numerous papers, contributed to the development of an international standard for distributed simulations, and has recently been working in a public-private collaboration to draft security recommendations for the smart grid.
Reed Little is a Senior Member of the Technical Staff at the SEI. He applies more than 35 years of experience in computer simulation, software architecture, software product lines, man-machine interface, artificial intelligence, and programming language design to various aspects of applied research and hands-on customer assistance for large (more than three million lines of code) software systems.
Paulo Merson has more than 20 years of software development experience. He works for the SEI in the areas of software architecture, service-oriented architecture, and aspect-oriented software development. He is also a practicing software architect in industry. One of his assignments at the SEI is to teach a two-day course in "Documenting Software Architectures" for industry and government practitioners. His speaking experience also includes tutorials at various conferences, such as SD Best Practices, Dr. Dobb's Architecture & Design World, and JavaOne. Prior to joining the SEI, he was a Java EE consultant. Paulo holds a B.Sc. in Computer Science from University of Brasilia, and a Master of Software Engineering from CMU.
Robert Nord is a Senior Member of the Technical Staff in the Research, Technology, and System Solutions Program at the SEI, where he works to develop and communicate effective methods and practices for software architecture. He is coauthor of the practitioner-oriented book Applied Software Architecture (Addison-Wesley, 2000) and lectures on architecture-centric approaches. He is a member of the IFIP Working Group on Software Architecture (WG2.10).
Judith Stafford is a Senior Lecturer at Tufts University and a Visiting Scientist at the SEI. Before joining the faculty at Tufts University, she was a Senior Member of the Technical Staff at the SEI in the Product Lines Systems Program, working in the Software Architecture Technologies Initiative. She has authored several book chapters on the topic of software architecture analysis, software architecture support for software component composition, and software architecture documentation. Stafford has been an organizer and program committee member for several conferences and workshops, and a guest editor on several leading software engineering journal special issues. She received her Ph.D. and M.S. degrees in Computer Science from the University of Colorado at Boulder. She is a member of the IEEE Computer Society, ACM SIGSOFT and SIGPLAN, and the IFIP Working Group on Software Architecture (WG2.10).
Content
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
P.1: A Short Overview of Software Architecture 1
P.2: A Short Overview of Architecture Documentation 9
P.3: Architecture Views 22
P.4: Architecture Styles 25
P.5: Seven Rules for Sound Documentation 36
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
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
1.1: Overview 55
1.2: Elements, Relations, and Properties of Module Views 56
1.3: What Module Views Are For 59
1.4: Notations for Module Views 60
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
2.1: Decomposition Style 65
2.2: Uses Style 74
2.3: Generalization Style 82
2.4: Layered Style 87
2.5: Aspects Style 104
2.6: Data Model 109
2.7: Summary Checklist 120
2.8: Discussion Questions 120
2.9: For Further Reading 121
Chapter 3: Component-and-Connector Views 123
3.1: Overview 123
3.2: Elements, Relations, and Properties of C&C Views 126
3.3: What C&C Views Are For 136
3.4: Notations for C&C Views 139
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
4.1: An Introduction to C&C Styles 155
4.2: Data Flow Styles 157
4.3: Call-Return Styles 161
4.4: Event-Based Styles 172
4.5: Repository Styles 178
4.6: Crosscutting Issues for C&C Styles 182
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
5.1: Overview 189
5.2: Deployment Style 191
5.3: Install Style 198
5.4: Work Assignment Style 202
5.5: Other Allocation Styles 206
5.6: Summary Checklist 213
5.7: Discussion Questions 213
5.8: For Further Reading 214
Part II: Beyond Structure: Completing the Documentation 215
Chapter 6: Beyond the Basics 217
6.1: Refinement 218
6.2: Descriptive Completeness 222
6.3: Documenting Context Diagrams 225
6.4: Documenting Variation Points 231
6.5: Documenting Architectural Decisions 239
6.6: Combining Views 250
6.7: Summary Checklist 258
6.8: Discussion Questions 259
6.9: For Further Reading 260
Chapter 7: Documenting Software Interfaces 261
7.1: Overview 261
7.2: Interface Documentation 265
7.3: A Standard Organization for Interface Documentation 271
7.4: Stakeholders of Interface Documentation 278
7.5: Conveying Syntactic Information 279
7.6: Conveying Semantic Information 280
7.7: Examples of Interface Documentation 281
7.8: Summary Checklist 285
7.9: Discussion Questions 286
7.10: For Further Reading 286
Chapter 8: Documenting Behavior 289
8.1: Beyond Structure 289
8.2: How to Document Behavior 290
8.3: Notations for Documenting Behavior 295
8.4: Where to Document Behavior 306
8.5: Why to Document Behavior 306
8.6: Summary Checklist 308
8.7: Discussion Questions 309
8.8: For Further Reading 311
Part III: Building the Architecture Documentation 313
Chapter 9: Choosing the Views 315
9.1: Stakeholders and Their Documentation Needs 316
9.2: A Method for Choosing the Views 326
9.3: Example 329
9.4: Summary Checklist 335
9.5: Discussion Questions 335
9.6: For Further Reading 335
Chapter 10: Building the Documentation Package 337
10.1: Documenting a View 337
10.2: Documentation Beyond Views 350
10.3: Documenting a Mapping to Requirements 357
10.4: Packaging the Architecture Documentation 362
10.5: Summary Checklist 372
10.6: For Further Reading 373
Chapter 11: Reviewing an Architecture Document 375
11.1: Steps of the Procedure 376
11.2: Sample Question Sets for Reviewing the Architecture Document 382
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
E.1: ISO/IEC 42010, nee ANSI/IEEE Std 1471-2000 400
E.2: Rational Unified Process/Kruchten 4+1 406
E.3: Using the Rozanski and Woods Viewpoint Set 408
E.4: Documenting Architecture in an Agile Development Project 414
E.5: U.S. Department of Defense Architecture Framework 419
E.6: Where Architecture Documentation Ends 428
E.7: A Final Word 429
E.8: For Further Reading 429
Appendix A: UML-Unified Modeling Language 431
A.1: Introduction 431
A.2: Documenting a Module View 433
A.3: Documenting a Component-and-Connector View 438
A.4: Documenting an Allocation View 443
A.5: Documenting Behavior 449
A.6: Documenting Interfaces 460
Appendix B: SysML-Systems Modeling Language 465
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
Appendix C: AADL-The SAE Architecture Analysis and Design Language 473
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
Foreword to the First Edition xxv
Preface xxix
Acknowledgments xxxiii
Reader's Guide xxxv
Prologue: Software Architectures and Documentation 1
P.1: A Short Overview of Software Architecture 1
P.2: A Short Overview of Architecture Documentation 9
P.3: Architecture Views 22
P.4: Architecture Styles 25
P.5: Seven Rules for Sound Documentation 36
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
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
1.1: Overview 55
1.2: Elements, Relations, and Properties of Module Views 56
1.3: What Module Views Are For 59
1.4: Notations for Module Views 60
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
2.1: Decomposition Style 65
2.2: Uses Style 74
2.3: Generalization Style 82
2.4: Layered Style 87
2.5: Aspects Style 104
2.6: Data Model 109
2.7: Summary Checklist 120
2.8: Discussion Questions 120
2.9: For Further Reading 121
Chapter 3: Component-and-Connector Views 123
3.1: Overview 123
3.2: Elements, Relations, and Properties of C&C Views 126
3.3: What C&C Views Are For 136
3.4: Notations for C&C Views 139
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
4.1: An Introduction to C&C Styles 155
4.2: Data Flow Styles 157
4.3: Call-Return Styles 161
4.4: Event-Based Styles 172
4.5: Repository Styles 178
4.6: Crosscutting Issues for C&C Styles 182
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
5.1: Overview 189
5.2: Deployment Style 191
5.3: Install Style 198
5.4: Work Assignment Style 202
5.5: Other Allocation Styles 206
5.6: Summary Checklist 213
5.7: Discussion Questions 213
5.8: For Further Reading 214
Part II: Beyond Structure: Completing the Documentation 215
Chapter 6: Beyond the Basics 217
6.1: Refinement 218
6.2: Descriptive Completeness 222
6.3: Documenting Context Diagrams 225
6.4: Documenting Variation Points 231
6.5: Documenting Architectural Decisions 239
6.6: Combining Views 250
6.7: Summary Checklist 258
6.8: Discussion Questions 259
6.9: For Further Reading 260
Chapter 7: Documenting Software Interfaces 261
7.1: Overview 261
7.2: Interface Documentation 265
7.3: A Standard Organization for Interface Documentation 271
7.4: Stakeholders of Interface Documentation 278
7.5: Conveying Syntactic Information 279
7.6: Conveying Semantic Information 280
7.7: Examples of Interface Documentation 281
7.8: Summary Checklist 285
7.9: Discussion Questions 286
7.10: For Further Reading 286
Chapter 8: Documenting Behavior 289
8.1: Beyond Structure 289
8.2: How to Document Behavior 290
8.3: Notations for Documenting Behavior 295
8.4: Where to Document Behavior 306
8.5: Why to Document Behavior 306
8.6: Summary Checklist 308
8.7: Discussion Questions 309
8.8: For Further Reading 311
Part III: Building the Architecture Documentation 313
Chapter 9: Choosing the Views 315
9.1: Stakeholders and Their Documentation Needs 316
9.2: A Method for Choosing the Views 326
9.3: Example 329
9.4: Summary Checklist 335
9.5: Discussion Questions 335
9.6: For Further Reading 335
Chapter 10: Building the Documentation Package 337
10.1: Documenting a View 337
10.2: Documentation Beyond Views 350
10.3: Documenting a Mapping to Requirements 357
10.4: Packaging the Architecture Documentation 362
10.5: Summary Checklist 372
10.6: For Further Reading 373
Chapter 11: Reviewing an Architecture Document 375
11.1: Steps of the Procedure 376
11.2: Sample Question Sets for Reviewing the Architecture Document 382
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
E.1: ISO/IEC 42010, nee ANSI/IEEE Std 1471-2000 400
E.2: Rational Unified Process/Kruchten 4+1 406
E.3: Using the Rozanski and Woods Viewpoint Set 408
E.4: Documenting Architecture in an Agile Development Project 414
E.5: U.S. Department of Defense Architecture Framework 419
E.6: Where Architecture Documentation Ends 428
E.7: A Final Word 429
E.8: For Further Reading 429
Appendix A: UML-Unified Modeling Language 431
A.1: Introduction 431
A.2: Documenting a Module View 433
A.3: Documenting a Component-and-Connector View 438
A.4: Documenting an Allocation View 443
A.5: Documenting Behavior 449
A.6: Documenting Interfaces 460
Appendix B: SysML-Systems Modeling Language 465
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
Appendix C: AADL-The SAE Architecture Analysis and Design Language 473
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
