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.
DEFINITION
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
A primary presentation, usually graphical, that depicts the primary elements and relationships of the view
An element catalog that explains and defines the elements shown in the view and lists their properties
A specification of the elements' interfaces and behavior
A variability guide explaining any built-in mechanisms available for tailoring the architecture
Rationale and design information
The documentation that applies to all of the views contains
An introduction to the entire package, including a reader's guide that helps a stakeholder find a desired piece of information quickly
Information describing how the views relate to one another, and to the system as a whole
Constraints and rationale for the overall architecture
Such management information as may be required to effectively maintain the whole package
COMING TO TERMS
Architectural Views
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.
The logical view primarily supports behavioral requirements: the services the system should provide to its end users. Designers decompose the system into a set of key abstractions, taken mainly from the problem domain. These abstractions are objects or object classes that exploit the principles of abstraction, encapsulation, and inheritance. In addition to aiding functional analysis, decomposition identifies mechanisms and design elements that are common across the system.
The process view addresses concurrency and distribution, system integrity, and fault tolerance. The process view also specifies which thread of control executes each operation of each class identified in the logical view. The process view can be seen as a set of independently executing logical networks of communicating programsprocessesthat are distributed across a set of hardware resources, which in turn are connected by a bus or a local area network or a wide area network.
The development view focuses on the organization of the software modules in the software development environment. The units of this view are small chunks of softwareprogram libraries or subsystemsthat can be developed by one or more developers. The development view supports the allocation of requirements and work to teams and supports cost evaluation, planning, monitoring of project progress, and reasoning about software reuse, portability, and security.
The physical view takes into account the system's requirements, such as system availability; reliability; performance; and scalability. This view maps the various elements identified in the logical, process, and development viewsnetworks, processes, tasks, and objectsonto the processing nodes.
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):
The conceptual view describes the system in terms of its major design elements and the relationships among them.
The module interconnection view encompasses two orthogonal structures: functional decomposition and layers.
The execution view describes the dynamic structure of a system.
The code view describes how the source code, binaries, and libraries are organized in the development environment.
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:
The technical architecture, concerned with the component execution environment, the set of tools, the user interface framework, and any other technical services/facilities required to develop and to run a component-based system
The application architecture, concerned with the set of architectural decisions, patterns, guidelines, and standards required to build a component-based system
The project management architecture, consisting of those elementsthe concepts, guidelines, principles, and management toolsneeded to build a scalable large system with a large team
The functional architecture, where the specification and implementation of the system reside.
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.