Documenting Software Architectures. Views and Beyond. 2nd Edition

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 modelsGuidance for documentation in an Agile development environmentDeeper treatment of documentation of rationale, reflecting best industrial practicesImproved templates, reflecting years of use and feedback, and more documentation layout optionsA new, comprehensive example (available online), featuring documentation of a Web-based service-oriented systemReference guides for three important architecture documentation languages: UML, AADL, and SySML Table of ContentsAbout the Cover xxiForeword to the Second Edition xxiiiForeword to the First Edition xxvPreface xxixAcknowledgments xxxiiiReader’s Guide xxxvPrologue: Software Architectures and Documentation 1P.1: A Short Overview of Software Architecture 1P.2: A Short Overview of Architecture Documentation 9P.3: Architecture Views 22P.4: Architecture Styles 25P.5: Seven Rules for Sound Documentation 36P.6: Summary Checklist 45P.7: Discussion Questions 46P.8: For Further Reading 47Part I: A Collection of Software Architecture Styles 49I.1: Three Categories of Styles 49I.2: Style Guides: A Standard Organization for Explaining a Style 50I.3: Choosing Which Element and Relation Properties to Document 52I.4: Notations for Architecture Views 53I.5: Examples 54Chapter 1: Module Views 551.1: Overview 551.2: Elements, Relations, and Properties of Module Views 561.3: What Module Views Are For 591.4: Notations for Module Views 601.5: Relation to Other Views 631.6: Summary Checklist 631.7: Discussion Questions 641.8: For Further Reading 64Chapter 2: A Tour of Some Module Styles 652.1: Decomposition Style 652.2: Uses Style 742.3: Generalization Style 822.4: Layered Style 872.5: Aspects Style 1042.6: Data Model 1092.7: Summary Checklist 1202.8: Discussion Questions 1202.9: For Further Reading 121Chapter 3: Component-and-Connector Views 1233.1: Overview 1233.2: Elements, Relations, and Properties of C&C Views 1263.3: What C&C Views Are For 1363.4: Notations for C&C Views 1393.5: Relation to Other Kinds of Views 1483.6: Summary Checklist 1503.7: Discussion Questions 1513.8: For Further Reading 152Chapter 4: A Tour of Some Component-and-Connector Styles 1554.1: An Introduction to C&C Styles 1554.2: Data Flow Styles 1574.3: Call-Return Styles 1614.4: Event-Based Styles 1724.5: Repository Styles 1784.6: Crosscutting Issues for C&C Styles 1824.7: Summary Checklist 1854.8: Discussion Questions 1864.9: For Further Reading 187Chapter 5: Allocation Views and a Tour of Some Allocation Styles 1895.1: Overview 1895.2: Deployment Style 1915.3: Install Style 1985.4: Work Assignment Style 2025.5: Other Allocation Styles 2065.6: Summary Checklist 2135.7: Discussion Questions 2135.8: For Further Reading 214Part II: Beyond Structure: Completing the Documentation 215Chapter 6: Beyond the Basics 2176.1: Refinement 2186.2: Descriptive Completeness 2226.3: Documenting Context Diagrams 2256.4: Documenting Variation Points 2316.5: Documenting Architectural Decisions 2396.6: Combining Views 2506.7: Summary Checklist 2586.8: Discussion Questions 2596.9: For Further Reading 260Chapter 7: Documenting Software Interfaces 2617.1: Overview 2617.2: Interface Documentation 2657.3: A Standard Organization for Interface Documentation 2717.4: Stakeholders of Interface Documentation 2787.5: Conveying Syntactic Information 2797.6: Conveying Semantic Information 2807.7: Examples of Interface Documentation 2817.8: Summary Checklist 2857.9: Discussion Questions 2867.10: For Further Reading 286Chapter 8: Documenting Behavior 2898.1: Beyond Structure 2898.2: How to Document Behavior 2908.3: Notations for Documenting Behavior 2958.4: Where to Document Behavior 3068.5: Why to Document Behavior 3068.6: Summary Checklist 3088.7: Discussion Questions 3098.8: For Further Reading 311Part III: Building the Architecture Documentation 313Chapter 9: Choosing the Views 3159.1: Stakeholders and Their Documentation Needs 3169.2: A Method for Choosing the Views 3269.3: Example 3299.4: Summary Checklist 3359.5: Discussion Questions 3359.6: For Further Reading 335Chapter 10: Building the Documentation Package 33710.1: Documenting a View 33710.2: Documentation Beyond Views 35010.3: Documenting a Mapping to Requirements 35710.4: Packaging the Architecture Documentation 36210.5: Summary Checklist 37210.6: For Further Reading 373Chapter 11: Reviewing an Architecture Document 37511.1: Steps of the Procedure 37611.2: Sample Question Sets for Reviewing the Architecture Document 38211.3: An Example of Constructing and Conducting a Review 39311.4: Summary Checklist 39511.5: Discussion Questions 39611.6: For Further Reading 396Epilogue: Using Views and Beyond with Other Approaches 399E.1: ISO/IEC 42010, nee ANSI/IEEE Std 1471-2000 400E.2: Rational Unified Process/Kruchten 4+1 406E.3: Using the Rozanski and Woods Viewpoint Set 408E.4: Documenting Architecture in an Agile Development Project 414E.5: U.S. Department of Defense Architecture Framework 419E.6: Where Architecture Documentation Ends 428E.7: A Final Word 429E.8: For Further Reading 429Appendix A: UML—Unified Modeling Language 431A.1: Introduction 431A.2: Documenting a Module View 433A.3: Documenting a Component-and-Connector View 438A.4: Documenting an Allocation View 443A.5: Documenting Behavior 449A.6: Documenting Interfaces 460Appendix B: SysML—Systems Modeling Language 465B.1: Architecture Documentation 466B.2: Requirements 466B.3: Documenting a Module View 468B.4: Documenting a Component-and-Connector View 469B.5: Documenting an Allocation View 470B.6: Documenting Behavior 471B.7: Documenting Interfaces 472B.8: Summary 472Appendix C: AADL—The SAE Architecture Analysis and Design Language 473C.1: Introduction 473C.2: Documenting a Module Style 475C.3: Documenting a Component-and-Connector View 478C.4: Documenting a Deployment View 481C.5: Documenting Behavior 482C.6: Documenting Interfaces 484C.7: Summary 484Acronyms 487Glossary 491References 497About the Authors 509About the Contributors 513Index 517 About the Authors 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).