Software archiecture lecture09

Documenting Software Documenting Software

Architectures

IntroductionIntroduction

• Architecture is the conceptual glue that holds every phase of the project together for all of its many • Architecture is the conceptual glue that holds every phase of the project together for all of its many stakeholders.• Documenting the architecture is the crowning step to crafting it• Documenting the architecture is the crowning step to crafting it• Even a perfect architecture is useless if no one understands it You must describe Architecture in sufficient detail, understands it • You must describe Architecture in sufficient detail, without ambiguity, and organized in such a way that others can quickly find needed information.This chapter will help you decide what information others can quickly find needed information.• This chapter will help you decide what information about an architecture is important to capture, and it will discuss guidelines for capturing it. It will also discuss notations that are available, including UML.will discuss guidelines for capturing it. It will also discuss notations that are available, including UML.

Uses of Architectural DocumentUses of Architectural Document

• Documentation is decidedly not a case of "one size fits all." • Documentation is decidedly not a case of "one size fits all." • It should be sufficiently abstract to be quickly understood by new employees but sufficiently detailed understood by new employees but sufficiently detailed to serve as a blueprint for analysis.• We should not expect to produce one architectural document and have every consumer read it in the same document and have every consumer read it in the same way. • Rather, we should produce documentation that helps a stakeholder quickly find the information that stakeholder stakeholder quickly find the information that stakeholder is interested in, with a minimum of information that is irrelevant (to that stakeholder) standing in the way.• This might mean producing different documents for • This might mean producing different documents for different stakeholders.


• One of the most fundamental rules for technical • One of the most fundamental rules for technical documentation is to write from the point of view of the reader.

• Understanding who the stakeholders are and how they will want to use the documentation will help us organize it and make it accessible to will help us organize it and make it accessible to and usable for them


Stakeholder Use

Architect and requirements engineers who represent customer(s)

To negotiate and make tradeoffs among competing requirements

Architect and designers of To resolve resource contention and establish performance and Architect and designers of constituent parts

To resolve resource contention and establish performance and other kinds of runtime resource consumption budgets

Implementors To provide inviolable constraints (plus exploitable freedoms) on downstream development activitiesdownstream development activities

Testers and integrators To specify the correct black-box behavior of the pieces that must fit together

Maintainers To reveal areas a prospective change will affectMaintainers

Designers of other systems with which this one must interoperate

To define the set of operations provided and required, and the protocols for their operation


Stakeholder Use

Quality attribute specialists To provide the model that drives analytical tools such as simulations and simulation generators, theorem provers, verifiers, etc. These tools require information about resource consumption, scheduling policies, dependencies, and so forth. Architecture documentation must contain the information necessary to documentation must contain the information necessary to evaluate a variety of quality attributes such as security, performance, usability, availability, and modifiability. Analyses for each attributes have their own information needs.

Managers To create development teams corresponding to work assignments Managers To create development teams corresponding to work assignments identified, to plan and allocate project resources, and to track progress by the various teams

Product line managers To determine whether a potential new member of a product family is in or out of scope, and if out by how muchis in or out of scope, and if out by how much

Quality assurance team To provide a basis for conformance checking, for assurance that implementations have been faithful to the architectural prescriptions

ViewsViews

• Recall that we defined a software architecture • Recall that we defined a software architecture for a system as The structure or structures of the system, which comprise elements, the externally visible properties of those elements, and the relationships the externally visible properties of those elements, and the relationships among them."

• The concept of a view, which you can think of as capturing a structure, provides us with the basic principle of documenting software architecture:principle of documenting software architecture:

Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one views and then adding documentation that applies to more than one view.

ViewsViews

• This principle is useful because it breaks the • This principle is useful because it breaks the problem of architecture documentation into more tractable parts, which provide the structure for the remainder of this chapter:structure for the remainder of this chapter:

▫ Choosing the relevant views

▫ Documenting a view▫ Documenting a view

▫ Documenting information that applies to more than one viewthan one view

Choosing the Relevant ViewsChoosing the Relevant Views

• What are the relevant views? • What are the relevant views?

▫ This is where knowing your stakeholders and the uses they plan to make of the documentation will help you construct the documentation package help you construct the documentation package they need.

• The views you should document depend on the • The views you should document depend on the uses you expect to make of the documentation


Decomposition

Deployment

Implementation

Stakeholder Decomposition

Uses

Class

Layer

C&C

Deployment

Implementation

Project Manager s s s d

Member of Development Team d d d d d s sMember of Development Team d d d d d s s

Testers and Integrators d d s s s

Maintainers d d d d d s s

Product Line Application Builder d s o s s sProduct Line Application Builder d s o s s s

Customer s o

End User s s

Analyst d d s d s dAnalyst d d s d s d

Infrastructure Support s s s s d

New Stakeholder x x x x x x x

Current and Future Architect d d d d d d sCurrent and Future Architect d d d d d d s

Key: d = detailed information, s = some details, o = overview information, x = anything


• Here is a simple three-step procedure for choosing • Here is a simple three-step procedure for choosing the views for your project.

1. Produce a candidate view list

▫ Begin by building a stakeholder/view table, like Table ▫ Begin by building a stakeholder/view table, like Table 9.2.

2. Combine views2. Combine views

▫ The candidate view list from step 1 is likely to yield an impractically large number of views

See if the stakeholders could be equally well served by ▫ See if the stakeholders could be equally well served by another view having a stronger constituency

▫ look for views that are good candidates to be ▫ look for views that are good candidates to be combined


• For example• For example

▫ The implementation view is often easily overlaid with the module decomposition view.

▫ The module decomposition view also pairs well with uses or layered views.

▫ The deployment view usually combines well with ▫ The deployment view usually combines well with whatever component-and-connector view shows the components that are allocated to hardware the components that are allocated to hardware elements—the process view.


3. Prioritize3. Prioritize

▫ Decide what to do first

▫ How you decide depends on the details specific ▫ How you decide depends on the details specific to your project.

▫ A project manager demands attention and information early and ofteninformation early and often

Documenting a ViewDocumenting a View

• There is no industry-standard template for documenting a view, but the seven-part standard • There is no industry-standard template for documenting a view, but the seven-part standard organization that we suggest in this section has worked well in practice1. Primary presentation1. Primary presentation2. Element catalog3. Context diagram4. Variability guide4. Variability guide5. Architecture background6. Glossary of terms7. Other information6. Glossary of terms7. Other information• Allocating specific information to specific sections will help the documentation writer attack the task and recognize completionwill help the documentation writer attack the task and recognize completion

Primary presentationPrimary presentation

• The primary presentation should contain the • The primary presentation should contain the information you wish to convey about the system

• The primary presentation is usually graphical and accompanied by explanation of the notation or symbol used.or symbol used.

• Sometimes the primary presentation can be tabulartabular

Element catalogElement catalog

• details at least those elements and relations • details at least those elements and relations depicted in the primary presentation

• Explains sufficient detail what elements are, and • Explains sufficient detail what elements are, and their purposes or the roles they play, rendered in the vocabulary of the view.

• In addition, if there are elements or relations • In addition, if there are elements or relations relevant to the view that were omitted from the primary presentation, the catalog is where those primary presentation, the catalog is where those are introduced and explained

Context diagramContext diagram

• shows how the system depicted in the view • shows how the system depicted in the view relates to its environment in the vocabulary of the view.

• For example, in a component-and-connector view you show which component and connectors interact with external components connectors interact with external components and connectors, via which interfaces and protocols.protocols.

Variability guideVariability guide

• shows how to exercise any variation points that are a part of the architecture shown in this view.part of the architecture shown in this view.• In some architectures, decisions are left unbound until a later stage of the development process• Variability guide should include:• Variability guide should include:1. the options among which a choice is to be made. ▫ In a module view, the options are the various versions or parameterizations of modules. parameterizations of modules. ▫ In a component-and-connector view, they might include constraints on replication, scheduling, or choice of protocol.▫ In an allocation view, they might include the conditions ▫ In an allocation view, they might include the conditions under which a software element would be allocated to a particular processor.

2. the binding time of the option. Some choices are made at design time, some at build time, and others at at design time, some at build time, and others at runtime

Architecture backgroundArchitecture background

• explains why the design reflected in the view came • explains why the design reflected in the view came to be. • The goal of this section is to explain to someone why the design is as it is and to provide a why the design is as it is and to provide a convincing argument that it is sound. • An architecture background includes1. rationale, explaining why the decisions reflected in 1. rationale, explaining why the decisions reflected in

the view were made and why alternatives were rejected.rejected.

2. analysis results, which justify the design or explain what would have to change in the face of a modification.modification.

3. assumptions reflected in the design.

Documenting InterfacesDocumenting Interfaces

• An interface is a boundary across which two independent entities meet and interact or communicate independent entities meet and interact or communicate with each other• Since you cannot perform analyses or system building without them, documenting interfaces is an important without them, documenting interfaces is an important part of documenting architecture.• Documenting an interface consists of naming and identifying it and documenting its syntactic and semantic identifying it and documenting its syntactic and semantic information• An interface is documented with an interface specificationspecification• Documenting an interface is a matter of striking a balance between disclosing too little information and disclosing too much.A rule of thumb is to focus on how elements interact disclosing too much.• A rule of thumb is to focus on how elements interact with their operational environments,

Documentation across ViewsDocumentation across Views

• Cross-view document capture the information that applies to more than one view.• Cross-view document capture the information that applies to more than one view.• Cross-view documentation consists of just three major aspects, which we can summarize as how-what-whyaspects, which we can summarize as how-what-why• How the documentation is laid out and organized so that a stakeholder can find the information efficiently and reliably. reliably. • What the architecture is. Here, the information that remains to be captured beyond the views themselves.• Why the architecture is the way it is: the context for the • Why the architecture is the way it is: the context for the system, external constraints that have been imposed to shape the architecture in certain ways, and the rationale for coarse-grained large-scale decisionsfor coarse-grained large-scale decisions

Template for Documenting InterfacesTemplate for Documenting Interfaces

• Here is a suggested standard organization for interface documentation.• Here is a suggested standard organization for interface documentation.

1. Interface Identity2. Resources provided2. Resources provided2.1 Resource syntax2.2 Resource semantics2.3 Resource usage restrictions2.3 Resource usage restrictions

3. Locally defined data types4. Exception definitions5. Variability provided5. Variability provided6. Quality attribute characteristics7. Element requirements8. Rationale and design issues8. Rationale and design issues9. Usage guide


• Interface identity. • Interface identity.

▫ When an element has multiple interfaces, identify the individual interfaces to distinguish them.

▫ You may also need to provide a version number

• Resource syntax

▫ The signature includes any information another ▫ The signature includes any information another program will need to write a syntactically correct program that uses the resource.program that uses the resource.

▫ The signature includes the resource name, names and logical data types of arguments (if any), and so forth.so forth.


• Resource semantics: This describes the result of • Resource semantics: This describes the result of invoking the resource. It might include

▫ Assignment of values to data that the actor invoking the resource can access (Where and How are values the resource can access (Where and How are values come from)

▫ Events that will be signaled or messages that will be ▫ Events that will be signaled or messages that will be sent as a result of using the resource

▫ How other resources will behave in the future as the result of using this resource.result of using this resource.

▫ Humanly observable results.

• Resource usage restrictions. • Resource usage restrictions.

▫ Under what circumstances may this resource be used


• Data type definitions• Data type definitions

▫ The architect should communicate the definition of data type that not provided by the underlying programming languageprogramming language

• Exception definitions

▫ These describe exceptions that can be raised by the ▫ These describe exceptions that can be raised by the resources on the interface.

• Variability provided by the interface

▫ configuration parameters and how they affect the ▫ configuration parameters and how they affect the semantics of the interface must be documented

▫ These configuration parameters and how they affect ▫ These configuration parameters and how they affect the semantics of the interface must be documented.


• Quality attribute characteristics of the interface• Quality attribute characteristics of the interface▫ This information may be in the form of constraints on implementations of elements that will realize the interfaceinterface

• Element requirements. ▫ What the element requires may be specific, named resources provided by other elements.resources provided by other elements.

• Rationale and design issues. ▫ The architect should record the reasons for an element's interface design. element's interface design. ▫ The rationale should explain the motivation behind the design, constraints and compromises what alternative designs were considered and rejected.design, constraints and compromises what alternative designs were considered and rejected.


• Usage guide• Usage guide

▫ In some cases semantics need to be reasoned about in terms of how a broad number of individual interactions interrelateindividual interactions interrelate

▫ Essentially, a protocol is involved that is documented by considering a sequence of documented by considering a sequence of interactions.

▫ Protocols can represent the complete behavior of ▫ Protocols can represent the complete behavior of the interaction or patterns of usage that the element designer expects to come up repeatedly.

Documentation across ViewsDocumentation across Views

• How the document is organized:• How the document is organized:

1. View catalog

2. View template2. View template

• What the architecture is:

1. System overview

2. Mapping between views (the way the views are 2. Mapping between views (the way the views are related to each other)

3. List of elements and where they appear3. List of elements and where they appear

4. Project glossary

• Why the architecture is the way it is: • Why the architecture is the way it is:

1. Rationale

View CatalogView Catalog

• A view catalog is the reader's introduction to the • A view catalog is the reader's introduction to the views• Each entry in catalog contains▫ The name of the view and what style it ▫ The name of the view and what style it instantiates▫ A description of the view's element types, relation ▫ A description of the view's element types, relation types, and properties▫ A description of what the view is for▫ Management information about the view ▫ Management information about the view document, such as the latest version, the location of the view document, and the owner of the view documentdocument

View TemplateView Template

• A view template is the standard organization for • A view template is the standard organization for a view.

• It helps a reader navigate quickly to a section of • It helps a reader navigate quickly to a section of interest, and it helps a writer organize the information and establish criteria for knowing how much work is left to do.how much work is left to do.

What the Architecture isWhat the Architecture is

• System Overview• System Overview�This is a short prose description of what the system's function is, who its users are, and any important background or constraintsimportant background or constraints• Mapping between Views�It’s reasonable that any two views will have �It’s reasonable that any two views will have much in common (describe same thing)

�Helping a reader of the documentation understand the relationships among views will understand the relationships among views will give him a powerful insight into how the architecture works as a unified conceptual architecture works as a unified conceptual whole.

What the Architecture isWhat the Architecture is

• Element List• Element List

�The element list is simply an index of all of the elements that appear in any of the views, along elements that appear in any of the views, along with a pointer to where each one is defined.

• Project Glossary

The glossary lists and defines terms unique to �The glossary lists and defines terms unique to the system that have special meaning

Why the Architecture is the way it isWhy the Architecture is the way it is

• Cross-view rationale explains how the overall • Cross-view rationale explains how the overall architecture is in fact a solution to its requirements.• the implications of system-wide design choices • the implications of system-wide design choices on meeting the requirements or satisfying constraints.constraints.• the effect on the architecture when adding a foreseen new requirement or changing an existing one.existing one.• the constraints on the developer in implementing a solution.implementing a solution.• decision alternatives that were rejected.

Unified Modeling Language (UML)Unified Modeling Language (UML)

• Today the Unified Modeling Language (UML) has • Today the Unified Modeling Language (UML) has emerged as the de facto standard notation for documenting a software architecture.

• It is up to the architect to augment the UML pictures with the necessary supporting documentation documentation

• UML provides no direct support for components, connectors, layers, interface semantics, or many connectors, layers, interface semantics, or many other aspects of a system that are supremely architectural.architectural.

UML - Module ViewsUML - Module Views

• Interfaces in UML• Interfaces in UML


• Examples of module notations in UML• Examples of module notations in UML


• Decomposition in UML with nesting• Decomposition in UML with nesting


• A simple representation of layers in UML• A simple representation of layers in UML

UML-Component and Connector ViewsUML-Component and Connector Views

• Five ways to represent interfaces to components• Five ways to represent interfaces to components

UML-Component and Connector ViewsUML-Component and Connector Views

• Systems as collaborations• Systems as collaborations

UML-Allocation ViewsUML-Allocation Views

• A deployment view in UML• A deployment view in UML

SummarySummary

• An architecture is worthless if nobody can • An architecture is worthless if nobody can understand what it is or how to use it• You must understand the stakeholders of the architecture and how they expect to use the architecture and how they expect to use the documentation• Treat the task of documenting an architecture as documenting the set of relevant views and then documenting the set of relevant views and then supplementing that with cross-view information• Box-and-line diagrams tell only a small part of the • Box-and-line diagrams tell only a small part of the story• Supporting documentation that explains the elements and relationships shown in diagrams are elements and relationships shown in diagrams are important parts

Software archiecture lecture09

Education

Transcript of Software archiecture lecture09