Documenting a Software Architecture

By Eng. Mohanned M. Dawoud

Architecture documentation is a thorny issue

Commonly there is no documentation covering the architecture. If it is, it’s out-of-date, inappropriate and

basically not very useful. Also projects that have masses of

architecture related information Sometimes invaluable, but often it’s out-of-

date, inappropriate and not very useful!

Others can understand/evaluate the design.

We can understand the design after a period of time.

Others in the project team and development organization can learn from the architecture.

We can do analysis on the design, perhaps to assess its likely performance, or to generate standard metrics.

No universally accepted architecture documentation standard.

An architecture can be complex, and documenting it in a comprehensible manner is time consuming and non-trivial.

An architecture has many possible views. Documenting all the potentially useful ones is time consuming and expensive.

An architecture design often evolves Keeping the architecture documents current is often forgotten, especially with time and schedule pressures in a project.

Project complexity A small project may only need a ‘marketecture’

Project longevity One-off stop gap software? Strategic, long-term, will evolve?

Needs of stakeholders Small team, a whiteboard might be ok Large, dislocated team needs more Integrators? Testers? Programmers?

Need to spend documentation dollars/euros wisely on high value products

In larger teams, and especially when groups are not co-located in the same offices or building, the architecture documentation becomes of vital importance for describing design elements such as: Component interfaces; Subsystems constraints; Test scenarios; third party component purchasing decisions; Team structure and schedule dependencies; External services to be offered by the application.

UML is a powerful way to document an architecture

Provides a relatively formal, unambiguous description

New features in UML 2.0 appropriate for architectures

Good tools available, some free Can be used to depict various

structural/behavioral architecture views

The structure diagrams define the static architecture of a model, and specifically are: Class diagrams: Show the classes in the

system and their relationships. Component diagrams: Describe the

relationship between components with well-defined interfaces. Components typically comprise multiple classes.

Package diagrams: Divide the model into groups of elements and describe the dependencies between them at a high level.

Deployment diagrams: Show how components and other software artifacts like processes are distributed to physical hardware.

Object diagrams: Depict how objects are related and used at run-time. These are often called instance diagrams.

Composite Structure diagrams: Show the internal structure of classes or components in terms of their composed objects and their relationships.

Behavior diagrams show the interactions and state changes that occur as elements in the model execute: Activity diagrams: Similar to flow charts, and

used for defining program logic and business processes.

Communication diagrams: Called collaboration diagrams in UML 1.x, they depict the sequence of calls between objects at run-time.

Sequence diagrams: Often called swim-lane diagrams after their vertical timelines, they show the sequence of messages exchanged between objects.

State Machine diagrams: Describe the internals of an object, showing its states and events, and conditions that cause state transitions.

Interaction Overview diagrams: These are similar to activity diagrams, but can include other UML interaction diagrams as well as activities. They are intended to show control flow across a number of simpler scenarios.

Timing diagrams: These essentially combine sequence and state diagrams to describe an object's various states over time and the messages that alter the object’s state.

Use Case diagrams: These capture interactions between the system and its environment, including users and other systems.

id Component View

OrderProcessing

MailQueue

SendEmail

MailServer

OrderSystem

CustomerSystem OrderQueue

«table»

NewOrders

1validate

1

readQ

1writeQ

1

read

1send

1

1readQ

1

1

writeQ

1

A UML component diagram for the order processing example

cd OrderProcessing

OrderReader

Validate Store

QueueWriter

1

1

1 1

1

1

Classes for the order processing component

sd Interactions

OrderReader

MailQueue

Validate

OrderQueue

Store QueueWriter

NewOrders CustomerSystem

readOrderData

success:=validateOrder

success:=newOrder

success:=storeOrder

success:=writeQueue

success:=acknowledgeOrderSuccess

success:=writeQueue

Sequence diagram for the order processing system

dd Deployment View

OrdersDB

OrderServer

«executable»

:OrderProcessing

«table»

:NewOrders

MOMServer

:MailQueue

:OrderQueue

MailServer

:MailServer

OrderSystem

CustomerSystem

«executable»

:CustomerSystem

«executable»

:OrderSystem

:SendEmail

CRM

ERP

SOAP

JDBC

UML Deployment diagram for the order processing system

id Component View

OrderProcessing

MailQueue

SendEmail

MailServer

OrderSystemCustomerSystem

OrderQueue

«table»

NewOrders

JDBC

SMTP

QueueRead

QueueRead

QueueWrite

CustomerServices

QueueWrite

Representing interfaces in the order processing example

id Component View

OrderProcessing

validateOrder

getOrders writeConfirmation

writeOrder

MailQueue

SendEmail

MailServer

OrderSystemCustomerSystem

validate

ProvidedInterface1

OrderQueue

«table»

NewOrders

JDBC

QueueWrite

QueueWrite

CustomerServices SMTP

QueueRead

QueueRead

cd Component View

OrderProcessing

getOrders

validateOrder

writeConfirmation

writeOrder

or: OrderReader

val: Validate

qw: QueueWriter

st: Store

«delegate»

«delegate»

«delegate»

«delegate»

Using ports in the order processing example

Internal design of the OrderProcessing component

Documentation is easier if there’s a template to use Reduces start-up time for projects by

providing ready-made document structures familiarity gained with the document structure

aids in the efficient capture of project design details.

help with the training of new staff

Architecture Documentation TemplateProject Name: XXX1 Project Context2 Architecture Requirements2.1 Overview of Key Objectives2.2 Architecture Use Cases2.3 Stakeholder Architectural

Requirements2.4 Constraints2.5 Non-functional Requirements2.6 Risks3 Solution3.1 Relevant Architectural Patterns3.2 Architecture Overview3.3 Structural Views3.4 Behavioral Views3.5 Implementation Issues4 Architecture Analysis4.1 Scenario analysis4.2 Risks

Some documentation is nearly always a good idea

Trick is to produce ‘just enough’ and no more requires upfront planning and thinking Commitment to keeps docs current

UML 2.0 makes architecture documentation easier

Some good UML 2.0 tools, try ‘em out.