ICS 125: Project in Software System Design
Fall Quarter 1999
Architecture and Module Specifications
Due Date
As described in the course syllabus.
Overview
After finalizing your requirements, your team shall develop a
design that fully satisfies the requirements for your
application. This deliverable will consist of two primary components:
a design specification (consisting of a high-level architectural design
and module specifications) and an integration test plan.
You may wish to do an object-oriented design and adhere to the Object
Modeling Technique. In this case, your design specification should
include the following three models: the object model, which consists of
object diagrams; the dynamic model, which consists of event traces and
state diagrams; and the functional model, which consists of data flow diagrams.
The design should describe all system level objects/tasks, operations,
the relationships between those objects/tasks, and external interaction
with the environment as well as object class specifications that further
detail the object design.
In conjunction with this object-oriented design, your team must develop
an integration test plan covering the
interfaces between specified modules and/or objects. The integration
test plan must cover all interactions between modules/objects by applying
functional test heuristics (black box) to each module/class interface in
the design specification and developing a test plan for each interaction
between modules and/or objects.
Your document must specify the correspondence between the
requirements specification and your design. You may show this
correspondence any way you feel is appropriate (e.g., make notations
throughout your document or using a table that cross-references
paragraph numbers).
Developing the software design will undoubtedly reveal inadequacies
in previous documents. Please note these problems and what was done to
solve them.
Don't forget to include your meeting minutes and performance appraisals
with your document; refer to the syllabus for the complete check-list of
what has to be turned in. As before, make sure that you post your design
document and your meeting minutes to your team web page.
Deliverable Objectives/Quality
Keep in mind that key objectives of a design document are to:
- Develop a coherent representation of software that will satisfy requirements
- Identify inadequacies in requirements
- Decompose the system into sub-systems that provide related sets of services
- Establish a framework for sub-system control and communication
- Specify modules that can be assigned as coding responsibilities
- Document design decisions and rationale
- Provide a reference tool readable by developers, testers, and maintainers
- Provide a basis for integration and testing
In addition, keep in mind that a design document should exhibit the
following qualities:
- Complete: everything that is essential is described
- Rigorous: expressed in a well-defined notation
- Consistent: no mismatched interfaces
- Uniform: the entire document is at same level of detail
- Modifiable: this document will change just like all the others
- Desensitized to change: hides implementation details and secrets
- Confirmable, verifiable and testable: you can tell when you've met the
design
Document Contents
Introduction
Expand your introduction to discuss your specific approaches to the
design of the system and the organization of this document. This
description is essentially just an updated version of the introduction
you included in your previous deliverable.
Understanding
Expand the understanding section of your previous document. Make sure
to add descriptions of what steps or actions you took to understand
each technology studied during this phase. If you make changes to this
section, add text describing why the change was necessary, and why it
more accurately reflects your new understanding. This section need not
be different if your understanding hasn't changed.
Project Plan
This will be an iterative expansion of your previous submission. Expand
your project plan to represent how you have accomplished the work so
far. Reassess the project risks. Expand your task network or work
breakdown structure to include the effort expended to complete this
task. Based on the work you have done, revise your estimates on how
much your team can accomplish and deliver.
If you make changes, add text describing why the change was
necessary or why it will improve the ability of your team to accomplish
the work you have proposed.
Design Specification
- Architecture Overview
- Architectural Style
What style of architecture did you adopt? Provide a reference to a
defining document.
- System Architecture Overview
This is the place for your "one great diagram" that shows how your
system is built. You might want to use more than one diagram, to show,
e.g., some different abstractions of the design (such as a data flow view,
a layers of abstraction view, an object view, or an OS process view)
- Subsystem Narrative
What each subsystem means
- Major limitations on the current design
-
Modules/Objects Specification
If you would like to use the Object Modelling Technique (OMT), see
the associated OMT
format as a suggestion.
- List of Modules/Objects within your system
- For each module/object, provide a Module Specification
- Name
- Definition/Purpose - what it is/does
- Narrative/Comment - how it works
- What are the interfaces or APIs? E.g., using Java terminology
public
private
protected
- Data - What state does it keep, what variables?
- Access - Who has access to the module/object/data?
- How does it fit into the inheritance/with/uses heirarchy?
- Constraints - what constraints are there for this object/module?
- Cardinality - How many will there be?
- Other useful diagrams : Uses, is-Composed-of, Design class diagrams, State
transition diagrams, API's Class-category diagrams, or other useful diagrams
Integration Test Plan
Includes an integration test plan capable of demonstrating that the
design meets the functionality specified in the requirements. Test
cases should cover each module/object and module/object interaction
specified in the design. You should consider each module/object as a
subsystem and apply functional (black box) test heuristics (such as
input/output coverage and error/exception coverage) to the parameters
identified in each operation in the interface. In addition, you should
develop a test case for each module/object interaction.
NOTE: if desired, the test cases can be grouped with the design
entity to which they apply, otherwise a cross reference listing of some
sort should be provided.
- For each test
- Test ID
- Purpose of Test
- Item(s) being tested
- Input specification
- Output specification
- Expected Results or Test Oracle Mechanism
- Test environmental needs or special test procedures
Initial Demonstration Plan
What and how will you demonstrate?
Tracking and Control Mechanisms
Configuration Management: how will your modules/objects be managed?
- file structure, sub-directories, Makefiles, etc.
- persistent data
Requirements Cross Reference: what modules/objects satisfy what requirements?
- a table mapping requirement to module/object
make sure it is complete and consistent.
Modifications to Prior Documents
Requirements
If any requirements changed, were added or deleted, this is the place
to make this explicit. Highlight why the requirement was
changed/added/deleted and by whom (customer, developer, etc.). Make
sure your requirements meet the objectives of completeness,
understandability, utility, unambiguity, and consistency. If your
requirements have not changed, then this section should be identical to
what you submitted earlier.
Glossary
Defines any terms used in the specifications above. This portion of
the document may be written as an extension to the glossary submitted
with the requirements, or may be a separate document that only defines
terms local to the design phase.
Additional Documentation
This section is reserved for any additional documentation developed
during this phase of the project. Specifically, if during the course of
developing the architecture your understanding of the various
technologies involved in the project changed, or you discovered items
that were not documented but which are important, include that
information here.
Also list here the major background sources that you used during
this phase or any that you plan to use during the remainder of the
project. This includes references to similar systems and/or
procedures.
Requirements Presentations/Reviews.
See the syllabus for dates.
Each team should prepare a 15 minute presentation, after which we will
allow up to 5 minutes of questions.
Prepare your presentation appropriately. Your presentation should include
the following:
- Some context for your project (brief!);
- Current state of your project plan;
- Highlights of your design including
- an overview of your architecture (this should comprise the bulk
of your presentation)
- one or more key module/object specifications;
- Modifications to your requirements that arose as a result of your design
process;
- Overview of your integration test plan.