Documenting Software Architecture: Documenting Behavior

Abstract : This report represents another milestone of a work in progress: a comprehensive handbook on how to produce high-quality documentation for software architectures. The handbook, tentatively titled Documenting Software Architectures, will be published in early 2002 by Addison-Wesley as part of the Software Engineering Institute (SEI) Series on Software Engineering. The book is intended to address a lack of language-independent guidance about how to capture an architecture in a written form that can provide a unified design vision to all of the stakeholders on a development project. A central precept of the book is that documenting an architecture entails two essential steps: 1) documenting the set of relevant views of that architecture and then completing the picture by 2) documenting information that transcends any single view. The book's audience is the community of practicing architects, apprentice architects, and developers who receive architectural documentation. This technical note describes ways to document an important but often overlooked aspect of software architecture: the behavior of systems, subsystems, and components.


Driving development activities
Behavioral documentation play the role of a vehicle of communication among stakeholders during system-development activities.
System decomposition.The behavior of an element has an important influence on the structure of its decomposition.
Implementing a system using a defined architecture is a continuous process of decomposition in smaller and more detailed elements until it is possible to describe the behavior in a programming language.
Simulation can be used during the development of the system.

What to document
At a minimum, we have to model the stimulation of actions, the transfer of information from an element to another, the time-related and ordering constraints of these interactions.Types of reactions of an element to its input: requires all of just some of its input to be present before it begins calculating.

How to document behavior: notations and languages
Any notation for documenting system behavior must include constructs for describing sequences of interactions.
Sequences of interactions are displayed as a set of stimuli and the triggered activities ordered by some means, for example a line, numbering, ordering from top to bottom.
As a description of behavior refers to structure, the structural elements can be part of the notation.
There are two type behavioral documentation tools: static views, traces.
Often tools of both types can be used together to support the design process.

Static views
This kind of behavioral documentation, shows the complete behavior of a structural element or set of elements.
Often tools of this type are state based .
It is referred as "static" because it is possible to infer all possible traces through a system.
The tools of this type need to support the description of alternatives and repetitions to provide the complete computing power .This type of documentation should be chosen when simulation is required or when static-analysis techniques will be used .Powerful graphic notation that allow us to trace the behavior of a system given specific inputs.
A lot of useful extensions to traditional state diagrams.
Nesting of states: when the superstate is entered, all substates are initiated at their respective default start state and they remain active until the superstate is exited.
Orthogonal regions: substates in orthogonal regions are activated concurrently upon entry to the superstate. . . .

Expressive power to model abstraction and concurrency .
Documenting Software Architecture: Documenting Behavior -p. 13

Statecharts: example
Sequence is represented by a single-headed arrow leading from the source state to the target state.
An arrow is annotated with a pair (cause event/generated event).

Z language: example
The ScheduleClass schema defines what it means to add a class to a schedule.
Above the center horizontal line there are the variable definitions.
The letter D signifies that a schema named Schedule exists and that all of its variables are available to ScheduleClass.
The variables that end in a question mark are input variables.
Below the center horizontal line there are first the pre-conditions for an operation and then the promised results of the transformations.
In this example the class will be added to the schedule and will be associated with the specified time.

Traces
Trace-oriented representations consist of sequences of activities or interactions that describe the system's response to a specific stimulus.
It is documented the trace of activities through a system described in terms of its structural elements and their interactions.
Trace descriptions can be used when we have to analyze specific difficult situation that the system has to deal with.
There are different techniques that emphasize particular aspects.

Message-oriented techniques focus on describing the message exchange between instances.
Component-oriented techniques focus on describing which behavioral features an element has to have to accommodate the system performing its functions.
Activity-oriented techniques focus on describing which activities have to be performed in order to achieve the purpose of the system.
Flow-oriented techniques focus on describing the sequencing of responsibilities of elements for a specific scenario or trace.

Sequence diagrams: example
Instances have a lifeline drawn as a vertical line along the time axis.

The arrows between lifelines can describe creation or destruction of instances.
Any other stimulus is depicted as an arrows between lifelines.
A stimulus can be annotated with a name of a function.
A stimulus represented as a dotted arrow describes a return of control to the sender of a previous stimulus.

Procedural sequence diagrams
This variation focuses on the interface interactions of elements and is more suitable to show concurrency , because it has means to show flow of control.
Thin boxes over the lifeline are the focus of control and are used to show that some computation is done by the instance in a precise interval of time.
Alternative paths and parallel execution can be described (in the figure respectively for "Originating Connection" and "Destinating Connection" .

Collaboration diagrams
Collaboration diagrams show the relationships among the interfaces of instances.
Collaboration diagrams are very useful when the task is to verify that a structure design can fulfill the functional requirements.
Collaboration diagrams are not useful if the understanding of concurrent actions is important (for example in performance analysis).
The relationships among the instances, called links, are also shown in collaborations diagram.Links are simple lines and only state that the two involved instances can interact.
Sequence diagrams and collaboration diagrams express similar informations.

Collaboration diagrams: example
The stimuli are shown as arrows attached to a link between instances.
Sequence numbers can be added to stimuli to show which stimulus follow which.
Sub-numbering can be used to show nested stimuli and/or parallelism.
With numbering, the information contained in this kind of diagrams is analogous to that obtainable from a sequence diagram but with the complexity the diagrams become unreadable.

MSCs
An MSC is a message-oriented representation that contains the description of the asynchronous communication between instances.
Simple MSCs can look like sequence diagrams, but they have a more specific definition and a richer notation.
Their main area of application is in telecommunication switching systems.
A big advantage of MSCs is that in addition to graphical representations, they have a textual specification language defined for them.
MSCs can often be seen in conjunction with the SDL (they are both defined by the International Telecommunication Union).
MSCs focus to represent the message exchange between instances (systems, processes).
SDL is used to describe what happen in a system or process.

MSCs: example
Instances are box with a vertical line.
The message flow is presented by arrows that can be horizontal, with a downward slope with respect to the direction to indicate the low of time.
A total ordering of the described communication events is assumed along each instance axis.
The frame represent the scope of the diagram.
Documenting Software Architecture: Documenting Behavior -p.35 For example: Types of lines interconnecting two elements: flow of data or flow of control.Types of communication: sync, async.Types of support for communication: channel, shared memory.
The authors describe four tools of this kind: statecharts ROOMcharts Specification Description Language (SDL) Z language (pronounced "zed") Documenting Software Architecture: Documenting Behavior -p. 12 Statecharts Formalism developed by David Harel in the 80s for describing reactive systems.