Perhaps the most important concept associated with software architecture documentation is that of the view. A software architecture is a complex entity that cannot be described in a simple one-dimensional fashion. Our analogy with the bird wing proves illuminating. There is no single rendition of a bird wing. Instead, there are many: feathers, skeleton, circulation, muscular views, and many others. Which of these views is the "architecture" of the wing? None of them. Which views convey the architecture? All of them.
A view is a representation of a set of system elements and the relationships associated with them.
In this book, we use the concept of views to give us the most fundamental principle of architecture documentation, illustrated in FigureP.1:
Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.
Figure P.1. A documentation package for a software architecture is composed of one or more view documents and documentation that explains how the views relate to one another, introduces the package to its readers, and guides them through it.
What are the relevant views? It depends on your goals. As we saw previously, architecture documentation can serve many purposes: a mission statement for implementers, a basis for analysis, the specification for automatic code generation, the starting point for system understanding and asset recovery, or the blueprint for project planning.
Different views also expose different quality attributes to different degrees. Therefore, the quality attributes that are of most concern to you and the other stakeholders in the system's development will affect the choice of what views to document. For instance, a layered view will tell you about your system's portability, a deployment view will let you reason about your system's performance and reliability, and so forth.
Different views support different goals and uses. This is fundamentally why we do not advocate a particular view or collection of views. The views you should document depend on the uses you expect to make of the documentation. Different views will highlight different system elements and/or relationships. According to Jazayeri, Ran, and van der Linden (2000, pp. 1617):
Many projects make the mistake of trying to impose a single partition in multiple component domains, such as equating threads with objects, which are equated with modules, which in turn are equated with files. Such an approach never succeeds fully, and adjustments eventually must be made, but the damage of the initial intent is often hard to repair. This invariably leads to problems in development and occasionally in final products.
It may be disconcerting that no single view can fully represent an architecture. Additionally, it feels somehow inadequate to see the system only through discrete, multiple views that may or may not relate to one another in any straightforward way. The essence of architecture is the suppression of information not necessary to the task at hand, and so it is somehow fitting that the very nature of architecture is such that it never presents its whole self to us but only a facet or two at a time. This is its strength: Each view emphasizes certain aspects of the system while deemphasizing or ignoring other aspects, all in the interest of making the problem at hand tractable. Nevertheless, no one of these individual views adequately documents the software architecture for the system. That is accomplished by the complete set of views along with information that transcends them. As Gamma et al. (1995, p. 22) say:
An object-oriented program's runtime structure often bears little resemblance to its code structure. The code structure is frozen at compile-time; it consists of classes in fixed inheritance relationships. A program's runtime structure consists of rapidly changing networks of communicating objects. In fact, the two structures are largely independent. Trying to understand one from the other is like trying to understand the dynamism of living ecosystems from the static taxonomy of plants and animals, and vice versa.
The documentation for a view contains
The documentation that applies to all of the views contains
COMING TO TERMS
Nearly three decades ago, Parnas (1974) observed that software consists of many structures, which he defined as partial descriptions showing a system as a collection of parts and showing some relations among the parts. This definition largely survives in architecture papers today. Parnas identified several structures prevalent in software. A few were fairly specific to operating systems, such as the structure that defines what process owns what memory segment, but others are more generic and broadly applicable. These include the module structurethe units are work assignments, the relation is-a-part-of or shares-part-of-the-same-secret-asthe uses structurethe units are programs, and the relation is depends on the correctness ofand the process structurethe units are processes, and the relation is gives computational work to.
More recently, Perry and Wolf (1992) recognized that, similar to building architecture, a variety of views of a system are required. Each view emphasizes certain architectural aspects that are useful to different stakeholders or for different purposes.
Later, Kruchten (1995) of the Rational Software Corpo-ration wrote an influential paper describing four main views of software architecture that can be used to great advantage in system building, along with a distinguished fifth view that ties the other four together: the "4+1" approach to architecture.
Finally, Kruchten prescribes using a small subset of important scenariosinstances of use casesto show that the elements of the four views work together seamlessly. This is the "+1" view, redundant with the others but serving a distinct purpose. The 4+1 approach has since been embraced as a foundation piece of the Rational Unified Process.
At about the same time, Soni, Nord, and Hofmeister of Siemens Corporate Research made a similar observation about views of architecture they observed in use in industrial practice. They wrote (1995):
These views have become known as the Siemens Four View model for architecture.
Other "view sets" are emerging. In their book Business Component Factory, Herzum and Sims (1999) prescribe these four as the most important:
Each view of a software architecture is used for a different purpose, often by different stakeholders. As such, the various views form the basic unit for documenting a software architecture.
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints