6.1.1 View Packets
Views of large software systems can contain hundreds or even thousands of elements. Showing these elements in a single presentation, along with the relations among them, can result in a blizzard of information that is indecipherable and contains far too much information for any stakeholder, who is concerned only with a certain part of the system. Architects need a way to present a view's information in digestible "chunks." We call these chunks view packets. Each view packet shows a fragment of the system. The documentation for a view, then, consists of a set of view packets, each showing a small portion of the system.
A view packet is the smallest cohesive bundle of documentation that you would give to a stakeholder, such as a development team or a subcontractor.
Same-View View Packets
The view packets that constitute a view are related to one another as either siblings or children.
View packets from the same view are related to one another as are the nodes of a tree structure; they document elements of the system that are siblings or parents and children of one another. To "move" from one view packet to another requires a series of operations that pan and tilt or zoom in and zoom out. View packets allow the architect to document a viewand a reader to understand a viewin
View Packets from Different Views
View packets from different views may be related to one another as well. In our Prologue discussion of styles, we said that no system is built from a single style. We used three cases; let's see how the concept of view packets lets us handle each one.
A bridging element is one that can appear in the view packets of two separate views. The element is common to both view packets and is used to provide the continuity of understanding from one view to the other.
In a case like this, one or more elements must occur in both views and have properties of both kinds of elements. (Otherwise, the two parts of the system could not communicate with each other.) These bridging elements provide the continuity of understanding from one view to the next and likely have multiple interfaces, each providing the mechanisms for letting the element work with other elements in each of the views to which it belongs.
To document this system, we would have a pipe-and-filter view packet that shows the pipe-and-filter portion of the system and a shared-data view packet that shows the shared-data part of the system. Bridging elements would appear in both, and the supporting documentationparticularly a mapping between viewswould make the correspondence clear, perhaps by showing the combined picture, as in Figure 6.1. Each view packet might be supplemented by view packets showing finer-grained parts of the system. In this example, neither top-level view packet shows the "whole" system, and each refers to the other as a cross-view sibling.
Figure 6.1. A system of pipe-and-filter and shared-data styles. Here, the bridging element, or element common to both, is the connector that takes the data stream from the last filter and translates it into a form deliverable to the database's interface. That connector will have a role that works with a filter's port and another that works with a database port.
Figure 6.2. A decomposition of an element in one style reveals substructure in a different style. Here, the server in this client-server system is designed as a pipe-and-filter system.
Figure 6.3. A system of pipes and filters with a shared database might be seen as exhibiting either of two styles.
Not all view packets from different views are related so cleanly to one another as shown in these three cases. If understanding the relation is important, however, they need to be documented.
View packets that represent a zoom-in operation are refinements of their parent. Architects use refinementthe gradual disclosure of information across a series of descriptionsto represent the information in a view.
Refinement is the process of gradually disclosing information across a series of descriptions.
Decomposition refinement is a refinement in which a single element is elaborated to reveal its internal structure, and then each member of that internal structure is recursively refined.
A decomposition refinement, or simply decomposition, elaborates a single element to reveal its internal structure and then recursively refines each member of that internal structure (see Figure 6.4). The text-based analogy of this is the outline, whereby major sections, denoted by roman numerals, are decomposed into subsections, denoted by capital letters, are decomposed into subsubsections, denoted by arabic numerals, and so forth.
Figure 6.4. (a) A hypothetical system consisting of three related elements: A, B, and C. (b) Element B consists of elements B1, B2, B3, and B4. Element B1 has responsibility for handling communication with the "outside" world, which here means outside of B.
Using decomposition refinements in a view carries an obligation to maintain consistency with respect to the relation(s) native to that view. For example, suppose that the relation shown in Figure 6.4(a) is send-data-to. Because element B is shown as both receiving and sending data, the refinement of B in Figure 6.4(b) must show where data can enter and leave B: in this case, via B1.
Implementation refinement is a refinement in which manyanimtext4 or all the elementsanimtext4 and relations are replaced by new, typically more implementation-specific, elements and relations.
Another kind of refinement, called an implementation refinement, shows the same systemor portion of the systemin which many or all the elements and relations are replaced by new, typically more implementation-specific, ones. For example, imagine two views of a publish-subscribe system. In one view, components are connected by a single event bus. In the refined view, the bus is replaced by a dispatcher to which the components make explicit calls to achieve their event announcements. By replacing the connector, we also have to change the interfaces of the components: Hence, we have implementation refinement. An implementation refinement is a case of a parent-child relation between view packets that belong to different viewswhere learning more detail about a system takes a reader from one view to another. In Figure 6.2, the pipe-and-filter system is an implementation refinement of the server.
6.1.3 Descriptive Completeness
Related to refinement is the concept of descriptive completeness, which tells how elements in view packets are related to one another. Figure 6.5 shows an architectural diagram for an imaginary system. Element A is related to element B in some waythe diagram does not disclose howB is related to C, and C is related to B. What can we conclude about whether A and C are related?
Figure 6.5. Element A is related to B, B is related to C, and C is related to B. What is the relation between A and C?
One possible answer is straightforward: A and C are not related, because the diagram shows no arrow between A and C. A second possible answer is a bit more complicated: This diagram reveals no relationship between A and C, but it is possible that this information was considered too detailed or tangential for the view packet in which this diagram appears. Therefore, the question cannot be answered at this time. Another view packet may subsequently reveal that A and C share this relation.
 A third answer is possible as well. If we happen to know that the relationwhatever it might beis transitive, we could deduce that it holds between A and C because it holds between A and B and between B and C. That case is not relevant for the discussion at hand, however.
Either answer is acceptable, as each represents a different strategy for documentation. The first strategy says that the view packets are written with descriptive completeness. This strategy tends to be used for packets that convey instructions or constraints to downstream designers or implementers. For instance, the layered view shows implementers what other elements they are allowed to useand, by extension, what elements they are prohibited from usingwhen coding their work assignments. If we gave Figure 6.5 to the coder of element A, we would want him or her to interpret the absence of an arrow between A and C as carrying meaning: namely, a prohibition from using element C.
Descriptively complete view packets show all elements and relations within the view they document.
The second strategy tends to be used for view packets intended to convey broad understanding. Suppose that we want to picture a system's data flow, so that a new project member can gain insight into how a result is computed or an important transaction is carried out. In that case, we might not want to show all data flow but only the data flow in the nominal, usual, or high-frequency cases. We might defer to another view packet, the data flow, when the system is doing, say, error detection and recovery. Suppose that Figure 6.5 shows that nominal case. Figure 6.6 might show the error case. A new programmer would eventually want to see both diagrams but not at once. Under this interpretation, Figure 6.6 does not contradict Figure 6.5 but augments it, whereas under the assumption of completeness, Figures 6.5 and 6.6 are contradictory; both cannot document the same system.
Figure 6.6. A supplement to Figure 6.5, showing alternative relationships among the elements. Under the assumption that descriptive completeness does not hold, this figure supplements Figure 6.5. Under the assumption of description completeness, the two figures taken together represent a conflict and hence an error.
So far, we've discussed these strategies in terms of relationships among elements, but we could also ask an element-related question. Suppose that Figure 6.5 purports to show an entire system or a specific portion of it. Ca n we then presume that A, B, and C are the only elements involved? That is, is every piece of software in A or in B or in C? The same two strategies apply. The first tells us, "Yes, you can presume that with impunity. All software within the scope of this view packet is shown in this view packet." The second says, "We don't know yet. Perhaps in a refinement or an augmentation of this view, another element will be shown."
If an error-logging element comes into play during error detection, a diagram like Figure 6.7 might apply. Again, both strategies are correct and have their place. In Section P.6, we admonished you to explain your notation. The issue of descriptive completeness is a special case of that. You simply need to specify which of the two strategies your documents follow. And, as we suggested, some documents may follow one, whereas others may follow the other. That is not a problem, as long as the reader is informed. So, if you adopt the completeness strategy, include one of the following statements in your documentation, as part of the notation key.
Figure 6.7. A refinement to Figure 6.5, showing an additional element, D
If you adopt the noncompleteness strategy, include one of the following statements in your key:
Earlier, we dealt with the issue of refinement. The issue of descriptive completeness is related. View packets that convey descriptive completeness also convey obligations on refinements. If a view packet shows no relationship (of whatever kind) between, say, elements A and C, no refinement of that view packet is allowed to subsequently show that relationship between A and C. If a view packet shows a set of elements, no new elements that are not part of those are allowed to be introduced later.
Descriptive completeness makes consistency checking among view packets much more straightforward but at the cost of making the diagrams and their explanation more cluttered and arguably more difficult to understand. As in many issues of architecture, this one brings with it an inherent trade-off.
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