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.

A UML component diagram for the order processing example

Classes for the order processing component

Sequence diagram for the order processing system

UML Deployment diagram for the order processing system

Representing interfaces in the order processing example

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 Template Project Name: XXX 1Project Context 2Architecture Requirements 2.1Overview of Key Objectives 2.2Architecture Use Cases 2.3Stakeholder Architectural Requirements 2.4Constraints 2.5Non-functional Requirements 2.6Risks 3Solution 3.1Relevant Architectural Patterns 3.2Architecture Overview 3.3Structural Views 3.4 Behavioral Views 3.5Implementation Issues 4Architecture Analysis 4.1 Scenario analysis 4.2Risks

 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.