What to Document

As mentioned, documented behavioral models support exploring the range of possible orderings of interactions, opportunities for concurrency, and time-based interaction dependencies among system elements. In this section, we provide guidance as to what types of things you will want to document in order to reap these benefits.

The exact nature of what to model depends on the type of system that is being designed. For example, if the system is a banking system, you focus on the order of eventsfor example, atomic transaction and rollback procedureswhereas in a real-time embedded system, you need to say a lot about timing properties in addition to the order of events. Another factor is the stage of development, or scope, of current decision making.

In early stages of development, for example, you typically want to talk about the elements and how they interact; not about the details of how input data is transformed into outputs, although it may be useful to say something about constraints on the transformational behavior within elements, inasmuch as that behavior affects the global behavior of the system.

At a minimum, you should model the stimulation of actions and transfer of information from one element to another. In addition, you might want to model time-related and ordering constraints on these interactions. If correct behavior depends on restrictions on the order in which actions must occur or combinations of actions that must have occurred before a certain action can be taken, these things must be documented. The more information that is documented and made explicit about the constraints on interactions, the more precise the analysis of system behavior can be, and the more likely that the implementation will exhibit the same qualities as those predicted during design.

8.4.1 Types of Communication

Looking at a structural diagram that depicts two interrelated elements, users of the documentation often ask, What does the line connecting the elements mean? Is it showing flow of data or control? A behavioral diagram provides a place to describe aspects of the transfer of information and the stimulation of actions from one element to another in more detail than you include in diagram keys.

Table 8.1 shows some common examples of various types of communication. In this table, we've classified types of communication along two axes. The first axis indicates the general purpose of the communication. In some cases, the primary purpose is to exchange data. In others, the primary purpose is to stimulate another element to signal that a task is completed or that a service is required. Often, however, a combination of the two is the main idea, as is the case when an element stimulates another to deliver data or when information is passed in messages or as parameters of events.

The second axis indicates the nature of the communication to some degree. In particular, whether elements communicate via synchronous or asynchronous communication is an important distinction. Remote procedure call is an example of synchronous communication. The sender and the receiver know about each other and synchronize in order to communicate. Messaging is an example of asynchronous communication. The sender does not concern itself with the state of the receiver when sending a message or posting an event. In fact, the sender and receiver may not be aware of each other's identity. Consider the telephone and e-mail as examples. If you make a phone call to someone, the person has to be at the phone in order for it to achieve its full purpose. That is synchronous communication. If you send an e-mail message and go on to other business, perhaps without concern for a response, the communication is asynchronous.

8.4.2 Constraints on Ordering

In the case of synchronous communication, you probably want to say more than that there is two-way communication. For instance, you may want to state which element initiated the communication and which element terminates it; you may want to say whether the target of the original message uses the assistance of other elements before it can respond to the original request. Decisions about how much detail to include in a behavioral model depend on what types of information you want to be able to get out of the model. For instance, if you are interested in performance analysis, it is important to know that an element will reach a point in its calculation where it requires additional input, as the length of total calculation depends on not only the internal calculation but also the delay associated with waiting for required inputs.

You will probably want to be more specific about certain aspects of the way an element reacts to its inputs. You may want to note whether an element requires all or just some of its inputs to be present before it begins calculating. You may want to say whether it can provide intermediate outputs or only final outputs. If a specific set of events must take place before an action of an element is enabled, that should be specified, as should the circumstances in which a set of events or element interactions will be triggered or the environment in which an output of an element is useful. These types of constraints on interactions provide information that is useful for analyzing the design for functional correctness, as well as for quality attributes.

8.4.3 Clock-Triggered Stimulation

If any activities are specified to take place at specific times or after certain intervals of time, some notion of time needs to be introduced into your documentation. Using two types of clocks is helpful. One clock measures calendar time to whatever precision is required for the type of system under construction. This clock allows you to specify that certain things are to happen at certain times of the day or month. For instance, you may want to specify some behavior differently for weekends and holidays. The other clock counts tics or another, perhaps more precisely specified, measure of time. This clock allows you to specify periodic actions, such as directions to check every 5 minutes and determine how many people are logged on to the system. Although it is clearly possible to compute one clock from the other, it is simpler to use both mechanisms when creating your architectural documentation, as these are two different ways of thinking about time.