Documenting Software Architectures: Views and Beyond / Edition 2

by Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers

Overview

“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

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

Product Details

ISBN-13:	9780321552686
Publisher:	Pearson Education
Publication date:	10/05/2010
Series:	SEI Series in Software Engineering
Edition description:	Second Edition
Pages:	592
Product dimensions:	6.40(w) x 9.30(h) x 1.40(d)

About the Author

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 c

Read an Excerpt

For all but the most trivial software system, success will be elusive if you fail to pay careful attention to its architecture: the way the system is decomposed into constituent parts and the ways those parts interact. Without an architecture that is appropriate for the problem being solved, the project will fail. Even with a superb architecture, if it is not well understood and well communicated—in other words, well documented—the project is likely to flounder.

Accordingly, software architecture is at the center of a frenzy of attention these days. A new book about it seems to pop out monthly. In response to industrial need, universities are adding software architecture to their software engineering curricula. It's now common for "software architect" to be a defined position in organizations, and professional practice groups for software architects are emerging. Software architecture has been the subject of major international conferences and workshops. The purveyors of the Unified Modeling Language (UML) promote their product by calling it "the standard notationfor software architecture," a claim that may say at least as much about the pervasiveness of architecture as about UML. The Software Engineering Institute of Carnegie Mellon University (SEI) maintains a bibliography of about 1,000 journal and conference papers on software architecture.

Rather surprisingly, practical guidance that is independent of language or notation for how to capture an architecture is lacking. To be sure, piles of books exist about how to use a particular language—again, UML comes to mind—but what an architect really needs is guidance in which architecture is a first-class citizen, with language relegated more appropriately to a supporting role.

First, let's agree on some basic context. The field has not anointed a single definition of software architecture, and so there are many, but we can specify the one we'll use, which is adapted from Bass, Clements, and Kazman (1998). Although much of this book is about the meaning of elements and relationships, we use this definition now to emphasize the plurality of structures that exist in architectures. Each structure is characterized by various kinds of elements and relationships, and each structure provides a view that imparts a particular kind of understanding of the architecture.

Definition: A software architecture for a system is the structure or structures of the system, which consist of elements, their externally visible properties, and the relationships among them.

"Externally visible properties" are those assumptions other components can make of a component, such as its provided services, quality attribute properties, shared resource usage, and so on.

The architecture serves as the blueprint for both the system and the project developing it, defining the work assignments that must be carried out by design and implementation teams. The architecture is the primary carrier of system qualities, such as performance, modifiability, and security, none of which can be achieved without a unifying architectural vision. Architecture is an artifact for early analysis to make sure that the design approach will yield an acceptable system. Architecture holds the key to post-deployment system understanding, maintenance, and mining efforts. In short, architecture is the conceptual glue that holds every phase of the project together for all its many stakeholders.

Documenting the architecture is the crowning step to crafting it. The perfect architecture is useless if it has not been expressed understandably. If you go to the trouble of creating a strong architecture, you must go to the trouble of describing it in enough detail, without ambiguity, and organized so that others can quickly find needed information. Otherwise, your effort will have been wasted, because the architecture will be unusable.

The audience for this book includes the people involved in the production and consumption of architectural documentation: the community of software developers. The goal of this book is to help you decide what information about an architecture is important to capture and to provide guidelines, notations, and examples for capturing it. We intend this book to be a practitioner-oriented guide to the various kinds of information that constitute an architecture. We give practical guidance for choosing what information should be documented and show—with examples in various notations, including but not limited to UML—how to describe that information in writing so that others can use it to carry out their architecture-based work: implementation, analysis, recovery, and so on. Therefore, we cover

• Uses of software architecture documentation. How one documents depends on how one wishes to use the documentation. We lay out possible end goals for architecture documentation and provide documentation strategies for each.
• Architectural views. We hold that documenting software architecture is primarily about documenting the relevant views and then augmenting this information with relevant information that applies beyond views. The heart of the book is an introduction to the most relevant architectural views, grouped into three major families, which we call viewtypes, along with practical guidance about how to write them down. Examples are included for each.
• Packaging the information. Once the views have been understood, the problem remains of choosing the relevant views, including information not contained in a view, and packaging all the information as a coherent whole. We give practical advice for all these facets.

We believe strongly in the importance of architecture in building successful systems. But no architecture can achieve this if it is not effectively communicated, and documentation is the key to successful communication. We hope that we have provided a useful handbook for practitioners in the field.

—P.C.C.,
Austin, Texas
—F.B., L.B., D.G., J.I., R.L., R.N., J.S.,
Pittsburgh, Pennsylvania

Table of Contents

• Prologue: Software Architectures and Documentation
• Part I: A Collection of Software Architecture Styles
• Chapter 1: Module Views
• Chapter 2: A Tour of Some Module Styles
• Chapter 3: Component-and-Connector Views
• Chapter 4: A Tour of Some Component-and-Connector Styles
• Chapter 5: Allocation Views and a Tour of Some Allocation Styles
• Part II: Beyond Structure: Completing the Documentation
• Chapter 6: Beyond the Basics
• Chapter 7: Documenting Software Interfaces
• Chapter 8: Documenting Behavior
• Part III: Building the Architecture Documentation
• Chapter 9: Choosing the Views
• Chapter 10: Building the Documentation Package
• Chapter 11: Reviewing an Architecture Document
• Epilogue: Using Views and Beyond with Other Approaches
• Appendix A: UML—Unified Modeling Language
• Appendix B: SysML—Systems Modeling Language
• Appendix C: AADL—The SAE Architecture Analysis and Design Language

Preface

For all but the most trivial software system, success will be elusive if you fail to pay careful attention to its architecture: the way the system is decomposed into constituent parts and the ways those parts interact. Without an architecture that is appropriate for the problem being solved, the project will fail. Even with a superb architecture, if it is not well understood and well communicated—in other words, well documented—the project is likely to flounder.

Accordingly, software architecture is at the center of a frenzy of attention these days. A new book about it seems to pop out monthly. In response to industrial need, universities are adding software architecture to their software engineering curricula. It's now common for "software architect" to be a defined position in organizations, and professional practice groups for software architects are emerging. Software architecture has been the subject of major international conferences and workshops. The purveyors of the Unified Modeling Language (UML) promote their product by calling it "the standard notationfor software architecture," a claim that may say at least as much about the pervasiveness of architecture as about UML. The Software Engineering Institute of Carnegie Mellon University (SEI) maintains a bibliography of about 1,000 journal and conference papers on software architecture.

Rather surprisingly, practical guidance that is independent of language or notation for how to capture an architecture is lacking. To be sure, piles of books exist about how to use a particular language—again, UML comes to mind—but what an architect really needs is guidance in which architecture is a first-classcitizen, with language relegated more appropriately to a supporting role.

First, let's agree on some basic context. The field has not anointed a single definition of software architecture, and so there are many, but we can specify the one we'll use, which is adapted from Bass, Clements, and Kazman (1998). Although much of this book is about the meaning of elements and relationships, we use this definition now to emphasize the plurality of structures that exist in architectures. Each structure is characterized by various kinds of elements and relationships, and each structure provides a view that imparts a particular kind of understanding of the architecture.

Definition: A software architecture for a system is the structure or structures of the system, which consist of elements, their externally visible properties, and the relationships among them.

"Externally visible properties" are those assumptions other components can make of a component, such as its provided services, quality attribute properties, shared resource usage, and so on.

The architecture serves as the blueprint for both the system and the project developing it, defining the work assignments that must be carried out by design and implementation teams. The architecture is the primary carrier of system qualities, such as performance, modifiability, and security, none of which can be achieved without a unifying architectural vision. Architecture is an artifact for early analysis to make sure that the design approach will yield an acceptable system. Architecture holds the key to post-deployment system understanding, maintenance, and mining efforts. In short, architecture is the conceptual glue that holds every phase of the project together for all its many stakeholders.

Documenting the architecture is the crowning step to crafting it. The perfect architecture is useless if it has not been expressed understandably. If you go to the trouble of creating a strong architecture, you must go to the trouble of describing it in enough detail, without ambiguity, and organized so that others can quickly find needed information. Otherwise, your effort will have been wasted, because the architecture will be unusable.

The audience for this book includes the people involved in the production and consumption of architectural documentation: the community of software developers. The goal of this book is to help you decide what information about an architecture is important to capture and to provide guidelines, notations, and examples for capturing it. We intend this book to be a practitioner-oriented guide to the various kinds of information that constitute an architecture. We give practical guidance for choosing what information should be documented and show—with examples in various notations, including but not limited to UML—how to describe that information in writing so that others can use it to carry out their architecture-based work: implementation, analysis, recovery, and so on. Therefore, we cover

• Uses of software architecture documentation. How one documents depends on how one wishes to use the documentation. We lay out possible end goals for architecture documentation and provide documentation strategies for each.
• Architectural views. We hold that documenting software architecture is primarily about documenting the relevant views and then augmen this information with relevant information that applies beyond views. The heart of the book is an introduction to the most relevant architectural views, grouped into three major families, which we call viewtypes, along with practical guidance about how to write them down. Examples are included for each.
• Packaging the information. Once the views have been understood, the problem remains of choosing the relevant views, including information not contained in a view, and packaging all the information as a coherent whole. We give practical advice for all these facets.

We believe strongly in the importance of architecture in building successful systems. But no architecture can achieve this if it is not effectively communicated, and documentation is the key to successful communication. We hope that we have provided a useful handbook for practitioners in the field.

—P.C.C.,
Austin, Texas
—F.B., L.B., D.G., J.I., R.L., R.N., J.S.,
Pittsburgh, Pennsylvania