se464/cs446/ece452 documenting software architecture and design
Post on 05-Jan-2016
59 Views
Preview:
DESCRIPTION
TRANSCRIPT
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
top related