1

SE464/CS446/ECE452

Documenting Software Architecture and Design

ByChang Hwan Peter Kim

www.ece.uwaterloo.ca/~ece452www.ece.uwaterloo.ca/~se446

2

• Sources used in preparing these slides:– Sample views for the PBX system by Sean Lau– Ian Sommerville, Software Engineering, 6th edition – Documenting Software Architecture: Documenting

Interfaces, Bachmann et al., SEI– How to Write Doc Comments for the Javadoc Tool,

Sun Microsystems– Documenting Component and Connector Views with

UML 2.0, Ivers et al., SEI– Slides from last year’s course taught by Professor

Czarnecki

3

Please note that the design document sample content used in these slides may not be complete or correct and should not be used without validation in your own project deliverables.

4

OverviewBasics of documenting software architecture and design• Views and Viewpoints• Design document for your class project

– Logical View (sec 2.1)– Development View (sec 2.2)– Process View (sec 2.3)– Physical View (sec 2.4)– Interfaces (sec 3.0)– Data Schema View (sec 4.0)– +1 View (sec 7.0)

• Further reading

5

Software Architecture and Design Documentation

• The Software Design Document (SDD) captures the design of a system

• At minimum, create a document describing the software architecture of a system (or be able to produce the document from a tool)

• You may package it into a separate document called Software Architecture Document

• A reasonable size for a Software Architecture Document for even a large system is 50-100 pages

• Alternatively, you may produce a series of smaller working documents as you progress with the development

6

Software Architecture and Design Documentation

• You may also capture the detailed design (in the SDD document or in a modeling tool)– It should be clear from a detailed design how to produce an

implementation, but…– A UML rendering of the implementation code is not a design

model (it’s an implementation model with limited value)– The gap between the architecture and the implementation for

smaller systems may be small, so you won’t need a detailed design– Or you may need detailed design only for some parts or aspects of

the system– Or your subsystems may be as big as to require their own

architecture document

7

Overview• Basics of documenting software architecture and designViews and Viewpoints• Design document for your class project

– Logical View (sec 2.1)– Development View (sec 2.2)– Process View (sec 2.3)– Physical View (sec 2.4)– Interfaces (sec 3.0)– Data Schema View (sec 4.0)– +1 View (sec 7.0)

• Further reading

8

The Need For Multiple Architectural Views

• Architecture and design is about system structure– How the system is decomposed into parts– Components and interactions with appropriate properties, enabling

appropriate analyses

• But this begs the question: what kinds of structure?• Many possibilities:

– Code structure– Run-time structure– Process structure– Work breakdown structure

• Each of these can be the basis of a Design View (or Architectural View)

9

The Need For Multiple Architectural Views

• Example: consider a building.– The contractor, the architect, interior designer, the

landscaper, and electrician all have a different view of the structure of the building.

– Although the view are pictured differently, all are inherently related.

– Together they describe the building’s “architecture”.• Software exhibits many structures and it is difficult to

communicate meaningfully about software unless it is clear which structure we are describing.

10

Kruchten’s “4+1 View Model” of the Architecture

• P. Kruchten. The 4+1 View Model of Architecture. In IEEE Software, vol. 12, no. 6, November 1995, pp. 42-50, IEEE 1995

Logical View DevelopmentView

Physical ViewProcess View

Use Cases,Scenarios

end-user:f unctionality

(class diagrams,interaction

diagrams, state-transition

diagrams, etc.)

programmers:sof tware

management(packages,

components,etc.)

systemengineers:topology,

communications(deployment

diagrams, etc.)

integrators:perf ormance,

scalability(process

diagrams, etc.)

Note: The concrete selection of views for a given project may vary,but the main contribution of having to support multiple views andtie them back to the requirements remains.

11

Basic Concepts in the IEEE Recommendation for Architectural Descriptions of Software-Intensive

Systems (IEEE Std. 1471)

• System stakeholder: “An individual, team, or organization (or class thereof) with interests in, or concerns relative to, a system.”

• View: “A representation of a whole system from the perspective of a related set of concerns.”

• Viewpoint: “A specification of the conventions for constructing and using a view. A pattern or template from which to develop individual views by establishing the purposes and audience for a view and the techniques for its creation and analysis.”

• Software development organizations may decide to create their own libraries of viewpoints covering their usual needs

12

Overview• Basics of documenting software architecture and design• Views and ViewpointsDesign document for your class project

– Logical View (sec 2.1)– Development View (sec 2.2)– Process View (sec 2.3)– Physical View (sec 2.4)– Interfaces (sec 3.0)– Data Schema View (sec 4.0)– +1 View (sec 7.0)

• Further reading

13

Logical View (sec 2.1)

• Use a component diagram to show provided/required interfaces and decomposition of components

• Describe each component’s responsibilities• Other important information, e.g.,

– Dependencies– Non-functional properties (e.g., maximum memory

usage, reliability, required test coverage, etc.)– Mandated implementation technology (e.g., EJB, COM,

etc.)

14

Logical View Example(using UML component diagram)

CallProcessor

«component»

AdminConsole

«component»

Database

«component»

Billing

«component»

IPhoneTester

IHardwareDatabase

IDatabase

IBillGenerator

• Description– CallProcessor: interaction between phone processes

• Provides an interface to test phones– AdminConsole: application logic and UI of admin application– Billing: bill generation and etc.– Database: persistence functionality

• Provides a separate interface for hardware-related information• Variability

– IDatabase may be a subinterface of IHardwareDatabase

May represent the process view if components are separate processes

15

Development View (sec 2.2)

• For each component, list– Source code artifacts (e.g., header file, C files, java files) used to

build it• Note that a source artifact can be shared among more than one

component (e.g., header files) – Deployment artifacts (e.g., exe file, jar archives, etc.) that

represent the executable to be deployed on a computing node– May also list other artifacts such as documentation, test plans, etc.

• Specify dependencies between artifacts, e.g.,– Include dependencies between source artifacts– Make dependencies for deployment artifacts

• May use tables and/or UML notation for artifacts and dependencies

16

Development View Example

17

Process View (sec 2.3)

• Static and dynamic organization of executable program units (e.g. processes, threads)

• If each component has its own process, then detailed information (e.g. thread organization and interaction) should be deferred to section 6 (Components)

18

Process View Example

• Note that despite the resemblance, the organization is different from the earlier component diagram

• Explanation parts where necessary (e.g. cardinality of association ends between CallMsgHandler and PhoneProcess)

• Dynamic organization (not shown)– Order of execution– A more detailed explanation of control/data dependency (e.g. through a scenario)– May use activity diagram / state chart

<<Process>>AdminConsole

<<Thread>>BillGenerator

<<Thread>>HardwareTester

<<Process>>PhoneProcess

<<Process>>CallMsgHandler

<<Process>>Database

0..*

1

1..*

0..*

1 1

1

1

1

1

1110..*

Reads/writes HW-related data

Reads/writes generic data

Reads/writes billing data

Requests manual phone test,

sets automatic test interval

Returns phone test resultExchanges call-related messages

19

Physical View (sec 2.4)

• Give a list of deployment artifacts; for each artifact, specify any deployment constraints (e.g., required hardware platform and resources)

• Show how deployment artifacts are distributed over computing nodes

• May use UML deployment diagrams

20

Physical View Example (using UML Deployment Diagram)

From: Scott Ambler, The Object Primer 3rd Edition: Agile Model Driven Development with UML 2, 2004

21

Interfaces (sec 3.0)• Specification of observable interaction with the

environment• All components have interfaces• A component’s interface contains view-specific

information• Interfaces are two way: provided and required• Spectrum of interaction constraints

– Simple existential dependency (e.g. requires resource X) to complex behavioural semantics (e.g. a protocol imposes a state-machine)

22

Interface Specification• Focus on observable interaction, rather than implementation• Possible elements

– Signature (mandatory)– Description– Pre-condition– Post-condition

• Side effects– Error-handling– Usage

• Example or more formal specification (like a protocol statechart)– Variability– Non-functional requirements

• Time-space constraints, usability constraints– Rationale and design issues

• Above elements may be described per message/method and/or per interface

23

Interface ExampleCallProcessor

«component»

AdminConsole

«component»

Database

«component»

Billing

«component»

IPhoneTester

IHardwareDatabase

IDatabase

IBillGenerator

«component»

:CallMsgHandler[1..*]

«component»

:PhoneProcess[2..*]

«component»

CallProcessor

<<delegate>>

IHardwareDatabase

<<delegate>>

IPhoneTester0..*

1..*

IPhoneProcess

ICallMsgHandler

Programmatic interface

Message-based interface

24

Programmatic interface (Java)/** * @author chpkim * * <p>This interface provides database read/write facilities for generic * (accounts, billing, hardware, etc.) information. */public interface IDatabase{ /** * Establishes connection to this database. * * @precondition Database connection information should be set. * @postcondition Database connection should be achieved before returning to caller. * @throws SQLException * @nfr Connection pooling has not been considered. Concurrent access * is limited to table-locking, not row-locking. */ public void connect() throws SQLException;

/** * Executes the specified statement on this database and return * the results if applicable. * * @param statement SQL statement to be executed * @return null if statement is not a query (does not start with SELECT). * non-null ResultSet otherwise. * @throws SQLException if query is malformed, connection is refused, etc. * @variability this method could be separated into two methods: * one for queries and one for non-queries */ public ResultSet execute(String statement) throws SQLException;}

-tag author-tag param-tag return-tag precondition:cmf:"Pre-conditions:"-tag postcondition:cmf:"Post-conditions:"-tag throws-tag nfr:a:"Non functional requirements:"-tag variability:a:"Variability:"-tag rationale:tm:"Rationale and Design Issues:"

Defining custom tags: specify a desired order of tags to javadoc.exe

Specifies where the tag is applicable to: Xaoptcmf (disable (X), all, overview, packages, types (interfaces, classes), constructors, methods, fields

Heading that will appear

25

Doclipse: javadoc support for Eclipse

• Text-completion (like code-completion)• Define attributes on tags

• Installation and more information:– http://www.beust.com/doclipse/

26

Why use javadoc?

• Uniformity

• Practical: industry-standard

• Automatic formatting

• Eliminates manual repetition– Interface documentation

generated from implementation and included in design

27

Message-based interfaceIPhoneProcess->ICallMsgHandler<RequestConnection>

<IP>IP address</IP></RequestConnection>

• Description: When phone is initially picked up, phone process requests connection

• Pre-condition: Idle state

• Post-condition: Grant or refusal with reason

• When a precise protocol is an accompanying document, aim towards understanding, rather than being overly precise and formal

• Runtime semantics may be included in “Behaviour” subsection of section 6.0 or in the interfaces section, as appropriate

• May be specified for whole or part of an interface, as appropriate

Idle

Wait for digit

OnHook / connections--

RequestConnection [connection available && valid permission] / ConnectionApproved

ICallMsgHandler IPhoneProcess

Idle

Caller off hook

PhoneOffHook / RequestConnection

Caller dial tone

ConnectionApproved

PhoneOnHook / OnHook

28

Data Schema View (sec 4.0)

• Provide a definition of all data structures referenced in the interfaces

• Specify database schemas• May use UML class diagrams, ER

diagrams, ASL, etc.• Be precise, especially in relationships

– Cardinality (what is “many”? 1..* or 0..*?)– Primary, foreign keys

29

Data Schema Example (using ER diagram notation)

Customer Customer_Account

1 1..*

Account_BillingPlan

Account

BillingPlan

0..1

0..*

CreationDateCustomerId

Name

LastName

FirstName

Attribute Type Description

CustomerId Integer Foreign key: References Customer(CustomerId)

Primary key: CustomerId and AccountId

AccountId Integer Foreign key. References Account(AccountId).

CreationDate Timestamp Stores the time a new account is created for a customer

Customer_Account

• Does Account represent one or multiple phones?

30

+1 View (sec 7.0)

• Explain how each use case is realized in the architecture by specifying the necessary interaction of components

• Document component interaction as textual descriptions of event flow or UML interaction diagrams for each use case from the requirements specification

31

Example of a ScenarioA request is made by the Call Handler to the Database Manager to acquire a channel

32

Keep in Mind…

• These are just some examples of useful views; however,…• Some of these views may not be appropriate for a given

system– The larger the system, the more dramatic the difference between

these structures– For small systems, the module and conceptual structures may so

similar they can be described together– E.g., no need for a separate process view if only one process in the

system or one process per component• Some other kinds of views may be required for the system

– E.g., control flow, data flow, timing, domain-specific views, etc.• You may also want to document mappings between

individual views

33

Overview• Basics of documenting software architecture and design• Views and Viewpoints• Design document for your class project

– Logical View (sec 2.1)– Development View (sec 2.2)– Process View (sec 2.3)– Physical View (sec 2.4)– Interfaces (sec 3.0)– Data Schema View (sec 4.0)– +1 View (sec 7.0)

Further Reading

34

Further Reading

• Paul Clements (Editor), Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, and Judith Stafford. Documenting Software Architectures: Views and Beyond. Addison Wesley Professional, ISBN: 0201703726; 1st edition, September, 2002