Return to How to Write Design Descriptions
Goto How to Capture IS User Requirements | Table of Contents
Goto How to Write Software Requirements Specifications | Table of Contents
Goto How to Write User Manuals | Table of Contents

Tuffley Computer Services Pty Ltd

Quality Management System

Software design descriptions standard

Preface

This document is a standard of Tuffley Computer Services Pty Ltd. For more information on this standard, contact the Technical Writer, Tuffley Computer Services Pty Ltd, Tel: (07) 3829 0131.

Revision History

Date	Ver.	Author	Comments
28/05/97	0.1	D. Tuffley	Create standard.
06/08/97	1.0	A. Tuffley	Amendments from review - approval

Copyright © Tuffley Computer Services Pty Ltd, 1995. This publication is copyright and contains information which is the property of Tuffley Computer Services Pty Ltd. No part of this document may be copied or stored in a retrieval system without the written permission of Directors.

Contents

Quality criteria
Traceability
Standards compliance
Completeness
Comprehensibility
Modularity
Cohesion
Coupling
Fan-in
Implementability
Modifiability
Extendability
Format & content
Cover page
Page marking
Introduction
Purpose
Scope
Definitions, acronyms & abbreviations (section.)
References
Design decomposition
Design structure
Code structure
Module detailed design description
Identification
Purpose
Function
Subordinates
Dependencies
Interface
Resources
Internal Data
Processing
Implementation process information
Unit test strategy
Interface design description
Identification
Type
Purpose
Function
Protocol
Error codes
User interaction
Database design
Introduction
Data Dictionary
Database design
Global memory
Messages
Introduction
User messages
Interprocess messages
Index
Appendix A - Structured English

1. Software Design Descriptions

1.1. Scope

This standard provides a guide for writing Software Design Descriptions (SDDs). It describes:

• the software development context in which an SDD should be created
• minimum requirements for SDD format and content and
• the qualities of a good SDD.

This standard represents a tailoring of the IEEE Std 1016 Recommended Practice for Software Design Descriptions. SDDs prepared in compliance with this standard will therefore also comply with IEEE Std 1016.

2. Definitions, acronyms & abbreviations

Design Entity: an element (component) of a design that is structurally and functionally distinct from other elements and that is separately named and referenced (IEEE Std 1016). An entity should describe a discrete system component that can be considered, implemented, changed and tested with minimal effect on other entities. Example: Software Module Detailed Design Description, Database Design, Memory Common Design, Interface Design.

Module: a program unit that is discrete and identifiable with respect to compiling, combining with other units, and loading; for example the input to or output from, an assembler, compiler, linkage editor, or executive routine (IEEE Std 610.12 - Standard Glossary of Software Engineering terminology). Note that the terms module, component and unit are used interchangeably.

Program Step: a single executable instruction in the target language. Program statements, selections and iterations are classed as single program steps. For example:

If {expression} then Step 1 (selection}
{instruction} Step 2 (statement)
else Step 3 (selection)
{instruction} Step 4 (statement)
end if
Do while {expression} Step 1 (iteration)
{instruction} Step 2 (statement)
end do

Note that compound statements such as:

{instruction} ; {instruction} ; {instruction}

are classed as multiple program steps.

SAS: System Architecture Specification - provides a framework for the development of the detailed design. It describes the partitioning of the design solution into individual hardware and software modules and describes the interaction between these modules. It does not provide detailed descriptions of the working of each module. This is the function of the Software Design Description.

SRS: Software Requirements Specification - a statement of what the system must do from the user's point of view.

SDD: Software Design Description - a detailed description of the workings of each software component.

SDL: State Definition Language.

Structure Chart: a diagram that identifies modules, activities or other entities in a system or computer program and shows how larger or more general entities break down into smaller, more specific entities.

System Architecture: a collection of hardware and software components and their interfaces that constitute the system.

White Box Testing: testing that takes into account the internal structure of a body of software thus ensuring that all branches and paths are traversed and all statements executed.

3. Purpose

The SDD is created by the System Architect or designer and is the major deliverable from the detailed design process.

3.1. Prerequisites

The prerequisite document required for an SDD varies according to the size and complexity of the software product to be developed (refer figure 1).

Large Systems. In the case of large and complex systems the prerequisite for the development of an SDD is the System Architecture Specification. In this context the SDD represents a further refinement of the design entities described in the SAS. An SDD may provide descriptions of one or more design entities.

Small Systems. In the case of small systems the SDD prerequisite is a Software Requirements Specification. In this context it is the single source of design solutions to problems stated in the SRS.

3.2. Use

The SDD is the primary reference for code development. As such, it must contain all the information required by a programmer to write code.

4. Quality criteria

This section addresses the criteria by which the quality of an SDD may be judged.

4.1. Traceability

Each design entity described in the SDD must satisfy a specific requirement specified in the Software Requirements Specification or an internal design requirement (i.e. an internal need for portability of a software product across many operating systems may create the need for an operating system services interface module).

4.2. Standards compliance

The SDD must address each issue specified in this standard. In practical terms this means that:

• all SDDs shall have the paragraph headings specified below
• if a paragraph heading is not applicable to the design it is to be included and marked not applicable
• all applicable paragraphs shall address the checklist of key points covered in each subsection of this standard.

4.3. Completeness

• Are all the requirements satisfied by design entities?
• Are all module input parameters used somewhere in the module?
• Are all output parameters assigned a value somewhere in the module?
• Does the design address:

Power fail/restart

Security

Reliability

Maintainability

Dealing with and recovering from hardware failure (i.e. disk, communications link).

4.4. Comprehensibility

• Are design concepts presented in simple, unambiguous language?
• Can design concepts be understood on the first reading?
• Does the design description state the obvious, leaving nothing to the imagination of the reader?

4.5. Modularity

This is the degree to which the big problem is broken up into smaller sub-problems, whose solutions may be pursued independently.

• Does each module deal with one simple self contained problem?
• Can a reviewer understand the module design on the first reading with only limited understanding of the complete system?
• Will the module design translate to a maximum of 100 program steps?
• Can the module be tested in isolation?

4.6. Cohesion

This is the degree to which internal elements of a module are related to each other.

• Can the module's function be described in one sentence with one subject and one verb?
• Does a module perform only one or two related functions.

Example:

Poor Cohesion - The Control Module detects incoming messages and passes them on to the appropriate message server, runs any time initiated tasks due, checks for failed communications links and attempts to resume communications.

Good Cohesion - The Control Module runs tasks a predefined times of the day.

4.7. Coupling

This is the degree to which individual modules are independent from each other.

Good - Data coupling. (A maximum of 5 parameters are passed between modules.)

Less Good - Control coupling. (One module controls the sequencing of steps in another module.)

Bad - Common coupling. (Several routines reference a single common data block.)

Very bad - Content coupling. (One module modifies local data values in another module.)

4.8. Fan-in

This is the number of superordinate modules that call a module.

• Maximise fan-in for good modularity
• Low fan in - absorb into other modules.

Fan-out (span of control)

This is the number of subordinate modules called by a module. A high fan-out (>7) may indicate that a module is too complex. That is, it contains too much control and coordination logic.

4.9. Implementability

The SDD must provide all information that the programmer requires to code the entity described.

4.10. Modifiability

Design information will be presented in one place only to support future modification of the document. An instance of more than one occurrence of the same information may result in ambiguity if all occurrences of the information are not updated simultaneously.

4.11. Extendability

This is the ease with which the design may be adapted to changes in requirements. Key elements of extendability are:

• Design simplicity
• Modularity. The more autonomous the modules in a software architecture, the higher the likelihood that a simple change will affect just one module rather than trigger a chain reaction across the whole system.

Return to How to Write Design Descriptions
Goto How to Capture IS User Requirements | Table of Contents
Goto How to Write Software Requirements Specifications | Table of Contents
Goto How to Write User Manuals | Table of Contents