Chunking Information: View Packets, Refinement, and Descriptive Completeness

Chunking Information View Packets, Refinement, and Descriptive Completeness

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.

DEFINITION

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.

• Sibling view packets document different parts of the same system. These view packets form a mosaic of the whole view, as if each partial view were a photograph taken by a camera that panned and tilted across the entire view.
• Children view packets document the same part of the system but in greater detail. These view packets come into focus when our hypothetical camera zooms in on a particular part of the system.

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

• Depth-first order: that is, choosing an element, documenting its substructure, choosing a subelement, documenting its substructure, and so on
• Breadth-first order: for all elements, documenting their substructures and then, for all those elements, documenting their substructures, and so on
• Some combination of the two, based on what the architect knows at the time

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.

DEFINITION

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.

1. Case 1: Different "areas" of the system exhibit different styles. For example, a system might use a pipe-and-filter style to process input data but then route the result to a database that is accessed by many elements. This system would be a blend of pipe-and-filter and shared-data styles. Documentation for this system would include a pipe-and-filter view that showed one part of the system and a shared-data view that showed the other part.

   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.

   

2. Case 2: An element playing a part in one style is itself composed of elements arranged in another style. For example, a server in a client-server system mightunknown to the other servers or to its own clientsbe implemented using a pipe-and-filter style. Documentation for this system would include a client-server view showing the overall system, as well as a pipe-and-filter view documenting that server, as shown in Figure 6.2. To document this system, one view packet in the client-server view will show the overall system whose elements are the clients, the server, and the connectors linking them. A view packet in the pipe-and-filter view will document that server. The pipe-and-filter view will not show the whole system but rather the part(s) to which it applies. The whole-system client-server view packet will refer to the server-as-pipe-and-filter view packet and vice versa as a cross-view child (parent).

   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.

   

3. Case 3: The same system may simply be seen in different lights, as though you were looking at it through filtered glasses. For example, the filters in a pipe-and-filter system each access a common data repository in the course of their processing, as shown in Figure 6.3. If we look through glasses that hide the pipes, the system exhibits the shared-data style. But if we look through glasses that hide the repository and the connectors to it, the system is clearly in the pipe-and-filter style. The glasses you choose will determine the style that you "see." Here, view packets in different views will show the same region of a system and at the same level of granularity. Each may have child view packets in its own view, as needed. The top-level view packets will refer to one another as siblings, showing the same information in a different view. Systems like this are also excellent candidates to be documented using combined views, in which the view packets show both kinds of information.

   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.

6.1.2 Refinement

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.

DEFINITION

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.

DEFINITION

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.[1]

[1] 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.

DEFINITION

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.

• If no relationship is shown beween two elements, that relationship either does not or is not allowed to exist between those two elements.
• The elements shown in this diagram account for all software in the system.

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:

• Subsequent refinements or other renditions of this view may show relationships among elements that are not shown here.
• Subsequent refinements or other renditions of this view may depict additional elements not shown here.

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.