Documenting Software Architectures: Views and Beyond

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

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).