Documenting Software Architectures: Views and Beyond [Hardcover]

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.

"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