Documenting Software Architectures: Views and Beyond, Second Edition

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 “This new edition is brighter, shinier, more complete, more pragmatic, more focused than the previous one, and I wouldn’t have thought it possible to improve on the original. As the field of software architecture has grown over these past decades, there is much more to be said, much more that we know, and much more that we can reflect upon of what’s worked and what hasn’t—and the authors here do all that, and more.” —From the Foreword by Grady Booch, IBM Fellow Cover......Page 1 Contents......Page 12 About the Cover......Page 24 Foreword to the Second Edition......Page 26 Foreword to the First Edition......Page 28 Preface......Page 32 Acknowledgments......Page 36 Reader’s Guide......Page 38 P.1.1 Overview......Page 44 P.1.2 Architecture and Quality Attributes......Page 45 Coming to Terms: What Is Software Architecture?......Page 46 Perspectives: What’s the Difference Between Architecture and Design?......Page 49 P.2.1 Why Document Software Architecture?......Page 52 Coming to Terms: Specification, Representation, Description, Documentation......Page 53 P.2.2 Uses and Audiences for Architecture Documentation......Page 55 P.2.3 Architecture Documentation and Quality Attributes......Page 60 P.2.4 Economics of Architecture Documentation......Page 61 P.2.5 The Views and Beyond “Method”......Page 62 P.2.7 Architectures That Change Faster Than You Can Document Them......Page 63 P.3 Architecture Views......Page 65 Coming to Terms: A Short History of Architecture Views......Page 66 P.4 Architecture Styles......Page 68 Coming to Terms: Module, Component......Page 72 Coming to Terms: “Architecture Style” and “Architecture Pattern”......Page 75 P.5 Seven Rules for Sound Documentation......Page 79 Perspectives: Beware Notations Everyone “Just Knows”......Page 81 Perspectives: Quivering at Arrows......Page 84 P.6 Summary Checklist......Page 88 P.7 Discussion Questions......Page 89 P.8 For Further Reading......Page 90 I.1 Three Categories of Styles......Page 92 I.2 Style Guides: A Standard Organization for Explaining a Style......Page 93 I.3 Choosing Which Element and Relation Properties to Document......Page 95 I.4 Notations for Architecture Views......Page 96 I.5 Examples......Page 97 1.1 Overview......Page 98 1.2 Elements, Relations, and Properties of Module Views......Page 99 1.3 What Module Views Are For......Page 102 1.4 Notations for Module Views......Page 103 1.6 Summary Checklist......Page 106 1.8 For Further Reading......Page 107 2.1 Decomposition Style......Page 108 2.2 Uses Style......Page 117 2.3 Generalization Style......Page 125 2.4 Layered Style......Page 130 2.5 Aspects Style......Page 147 2.6 Data Model......Page 152 2.8 Discussion Questions......Page 163 2.9 For Further Reading......Page 164 3.1 Overview......Page 166 3.2 Elements, Relations, and Properties of C&C Views......Page 169 3.3 What C&C Views Are For......Page 179 3.4 Notations for C&C Views......Page 182 3.5 Relation to Other Kinds of Views......Page 191 3.6 Summary Checklist......Page 193 3.7 Discussion Questions......Page 194 3.8 For Further Reading......Page 195 4.1 An Introduction to C&C Styles......Page 198 4.2 Data Flow Styles......Page 200 4.3 Call-Return Styles......Page 204 4.4 Event-Based Styles......Page 215 4.5 Repository Styles......Page 221 4.6 Crosscutting Issues for C&C Styles......Page 225 4.7 Summary Checklist......Page 228 4.8 Discussion Questions......Page 229 4.9 For Further Reading......Page 230 5.1 Overview......Page 232 5.2 Deployment Style......Page 234 5.3 Install Style......Page 241 5.4 Work Assignment Style......Page 245 5.5 Other Allocation Styles......Page 249 5.7 Discussion Questions......Page 256 5.8 For Further Reading......Page 257 Part II: Beyond Structure: Completing the Documentation......Page 258 Chapter 6 Beyond the Basics......Page 260 6.1 Refinement......Page 261 6.2 Descriptive Completeness......Page 265 6.3 Documenting Context Diagrams......Page 268 6.4 Documenting Variation Points......Page 274 6.5 Documenting Architectural Decisions......Page 282 6.6 Combining Views......Page 293 6.7 Summary Checklist......Page 301 6.8 Discussion Questions......Page 302 6.9 For Further Reading......Page 303 7.1 Overview......Page 304 7.2 Interface Documentation......Page 308 7.3 A Standard Organization for Interface Documentation......Page 314 7.4 Stakeholders of Interface Documentation......Page 321 7.5 Conveying Syntactic Information......Page 322 7.6 Conveying Semantic Information......Page 323 7.7 Examples of Interface Documentation......Page 324 7.8 Summary Checklist......Page 328 7.10 For Further Reading......Page 329 8.1 Beyond Structure......Page 332 8.2 How to Document Behavior......Page 333 8.3 Notations for Documenting Behavior......Page 338 8.5 Why to Document Behavior......Page 349 8.6 Summary Checklist......Page 351 8.7 Discussion Questions......Page 352 8.8 For Further Reading......Page 354 Part III: Building the Architecture Documentation......Page 356 Chapter 9 Choosing the Views......Page 358 9.1 Stakeholders and Their Documentation Needs......Page 359 9.2 A Method for Choosing the Views......Page 369 9.3 Example......Page 372 9.6 For Further Reading......Page 378 10.1 Documenting a View......Page 380 10.2 Documentation Beyond Views......Page 393 10.3 Documenting a Mapping to Requirements......Page 400 10.4 Packaging the Architecture Documentation......Page 405 10.5 Summary Checklist......Page 415 10.6 For Further Reading......Page 416 Chapter 11 Reviewing an Architecture Document......Page 418 11.1 Steps of the Procedure......Page 419 11.2 Sample Question Sets for Reviewing the Architecture Document......Page 425 11.3 An Example of Constructing and Conducting a Review......Page 436 11.4 Summary Checklist......Page 438 11.6 For Further Reading......Page 439 Epilogue: Using Views and Beyond with Other Approaches......Page 442 E.1.1 Overview......Page 443 E.1.2 42010 and Views and Beyond......Page 447 E.2.1 RUP/4+1 and Views and Beyond......Page 449 E.3 Using the Rozanski and Woods Viewpoint Set......Page 451 Coming to Terms: Architecture Perspectives......Page 453 E.3.1 Rozanski and Woods Viewpoints and Views and Beyond......Page 454 E.4.1 Overview......Page 457 E.4.2 Agile Development and Views and Beyond......Page 458 E.5.1 Overview of DoDAF......Page 462 E.5.3 DoDAF and Views and Beyond......Page 464 E.5.4 A Strategy to Use DoDAF to Document Software Architecture......Page 469 E.6 Where Architecture Documentation Ends......Page 471 E.8 For Further Reading......Page 472 A.1 Introduction......Page 474 A.2.2 Uses Style......Page 476 A.2.5 Aspects Style......Page 477 A.2.6 Data Model Style......Page 478 Perspectives: UML Class Diagrams: Too Much, Too Little......Page 479 A.3 Documenting a Component-and-Connector View......Page 481 A.4.1 Deployment Style......Page 486 A.4.2 Install and Implementation Styles......Page 488 A.4.3 Work Assignment Style......Page 489 A.5 Documenting Behavior......Page 492 A.5.2 Sequence Diagram......Page 493 A.5.3 Communication Diagram......Page 496 A.5.4 Timing Diagram......Page 497 A.5.5 Interaction Overview Diagram......Page 498 A.5.6 State Machine Diagram......Page 500 A.5.7 Use Case Diagram......Page 501 A.6 Documenting Interfaces......Page 503 Perspectives: UML Tools......Page 504 Appendix B: SysML—Systems Modeling Language......Page 508 B.2 Requirements......Page 509 B.3 Documenting a Module View......Page 511 B.4 Documenting a Component-and-Connector View......Page 512 B.5 Documenting an Allocation View......Page 513 B.6 Documenting Behavior......Page 514 B.8 Summary......Page 515 C.1 Introduction......Page 516 C.2 Documenting a Module Style......Page 518 C.3 Documenting a Component-and-Connector View......Page 521 C.4 Documenting a Deployment View......Page 524 C.5 Documenting Behavior......Page 525 C.7 Summary......Page 527 Acronyms......Page 530 A......Page 534 D......Page 535 M......Page 536 S......Page 537 U......Page 538 W......Page 539 References......Page 540 About the Authors......Page 552 About the Contributors......Page 556 A......Page 560 B......Page 562 C......Page 563 D......Page 565 E......Page 567 H......Page 568 I......Page 569 L......Page 570 M......Page 571 P......Page 572 R......Page 574 S......Page 575 T......Page 577 U......Page 578 V......Page 579 Z......Page 580