Home Random Page


CATEGORIES:

BiologyChemistryConstructionCultureEcologyEconomyElectronicsFinanceGeographyHistoryInformaticsLawMathematicsMechanicsMedicineOtherPedagogyPhilosophyPhysicsPolicyPsychologySociologySportTourism






Documentation generators

Documentation generators allow the automatic production of help and documentation from the information in the code. They help maintain consistency between code and documentation, and make the process of documentation truly concurrent with the coding.

Code generators (see Section 4.3.2) may include toots for automatically generating documentation about the screens, windows and reports that the programmer creates.

Configuration managers

Configuration management is covered in ESA PSS-05-09, 'Guide to Software Configuration Management'. Implementers should consider the use of an automated configuration manager in the circumstances of each project.

A variety of tools, often centred on a database, is available to assist in controlling the development of software when many modules may exist in many versions. Some tools allow the developer to specify a configuration (m modules in n versions), and then automatically compile, link, and archive it. The use of configuration management tools becomes essential when the number of modules or versions becomes large.

 

ESA PSS-05-05 Issue 1 (May 1992) 55 THE DETAILED DESIGN DOCUMENT

CHAPTER 5 THE DETAILED DESIGN DOCUMENT

INTRODUCTION

The purpose of a DDD is to describe the detailed solution to the problem stated in the 3RD. The DDD must be an output of the DD phase (DD13). The DDD must be complete, accounting for all the software requirements in the 3RD (DD15). The DDD should be sufficiently detailed to allow the code to be implemented and maintained. Components (especially interfaces) should be described in sufficient detail to be fully understood.

5.2 STYLE

The style of a DDD should be systematic and rigorous. The language and diagrams used in a DDD should be clear and constructed to a consistent plan. The document as a whole must be modifiable.

Clarity

A DDD is clear if it is easy to understand. The structure of the DDD must reflect the structure of the software design, in terms of the levels and components of the software (DD14). The natural language used in a DDD must be shared by all the development team.

The DDD should not introduce ambiguity. Terms should be used accurately.

A diagram is clear if it is constructed from consistently used symbols, icons, or labels, and is well arranged. Important visual principles are to:

• emphasise important information:

• align symbols regularly:

• allow diagrams to be read left-to-right or top-to-bottom:

• arrange similar items in a row, in the same style;

• exploit visual symmetry to express functional symmetry:

• avoid crossing lines and overlaps;

• avoid crowding.

 

56 ESA PSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

Diagrams should have a brief title, and be referenced by the text which they illustrate.

Diagrams and text should complement one another and be as closely integrated as possible. The purpose of each diagram should be explained in the text, and each diagram should explain aspects that cannot be expressed in a few words. Diagrams can be used to structure the discussion in the text.



Consistency

The DDD must be consistent. There are several types of inconsistency:

• different terms used for the same thing;

• the same term used for different things;

• incompatible activities happening simultaneously:

• activities happening in the wrong order.

Where a term could have multiple meanings, a single meaning should be defined in a glossary, and only that meaning should be used in the DDD.

Duplication and overlap lead to inconsistency. Clues to inconsistency are a single functional requirement tracing to more than one component. Methods and tools help consistency to be achieved.

Consistency should be preserved both within diagrams and between diagrams in the same document. Diagrams of different kinds should be immediately distinguishable.

Modifiability

A DDD is modifiable if changes to the document can be made easily, completely, and consistently. Good tools make modification easier, although it is always necessary to check for unpredictable side-effects of changes. For example a global string search and replace capability can be very useful, but developers should always guard against unintended changes.

Diagrams, tables, spreadsheets, charts and graphs are modifiable if they are held in a form which can readily be changed. Such items should be prepared either within the word processor, or by a tool compatible with the word processor. For example, diagrams may be

 

ESA PSS-05-05 Issue 1 (May 1992) 57 THE DETAILED DESIGN DOCUMENT

imported automatically into a document: typically, the print process scans the document for symbolic markers indicating graphics and other files.

Where graphics or other data are prepared on the same hardware as the code, it may be necessary to import them by other means. For example, a screen capture utility may create bitmap files ready for printing. These may be numbered and included as an annex. Projects using methods of this kind should define conventions for handling and configuration management of such data.

EVOLUTION

The DDD should be put under change control by the developer at the start of the Transfer Phase. New components may need to be added and old components modified or deleted. If the DDD is being developed by a team of people, the control of the document may be started at the beginning of the DD phase.

The Software Configuration Management Plan defines a formal change process to identify, control, track and report projected changes, as soon as they are first identified. Approved changes in components must be recorded in the DDD by inserting document change records and a document status sheet at the start of the DDD.

RESPONSIBILITY

Whoever writes the DDD, the responsibility for it lies with the developer. The developer should nominate people with proven design and implementation skills to write the DDD.

MEDIUM

The DDD is usually a paper document. The DDD may be distributed electronically when participants have access to the necessary equipment.

CONTENT

The DDD is the authoritative reference document on how the software works. Part 2 of the DDD must have the same structure and identification scheme as the code itself, with a 1:1 correspondence

 

58 ESAPSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

between sections of the documentation and the software components (DD14). The DDD must be complete, accounting for all the software requirements in the 3RD (DD15).

The DDD should be compiled according to the table of contents provided in Appendix Ρ of ESA PSS-05-0. This table of contents is derived from ANSI/IEEE Std 1016-1987 IEEE Recommended Practice for Software Design Descriptions' [Ref. 5]. This standard defines a Software Design Description as a 'representation or model of the software system to be created. The model should provide the precise design information needed for the planning, analysis and implementation of the software system'. The DDD should be such a Software Design Description.

The table of contents is reproduced below. Relevant material unsuitable for inclusion in the contents list should be inserted in additional appendices. If there is no material for a section then the phrase 'Not Applicable' should be inserted and the section numbering preserved.

Service Information:

a- Abstract

b - Table of Contents

ρ - Document Status Sheet

d - Document Change Records made since last issue

Part 1- General Description

1 Introduction

1.1 Purpose

1.2 Scope

1.3 Definitions, acronyms and abbreviations

1.4 References

1.5 Overview

2 Project Standards, Conventions and Procedures

2.1 Design standards

2.2 Documentation standards

2.3 Naming conventions

2.4 Programming standards

2.5 Software development tools

 

ESA PSS-05-05 Issue 1 (May 1992) 59 THE DETAILED DESIGN DOCUMENT

Part 2 - Component Design Specifications

n [Component identifier]

n.l Type

n.2 Purpose

n.3 Function

n.4 Subordinates

n.5 Dependencies

n.6 Interfaces

n.7 Resources

n.8 References

n.9 Processing

n.10 Data

Appendix A Source code listings

Appendix Β Software Requirements vs Components Traceability

matrix

A component may belong to a class of components that share characteristics. To avoid repeatedly describing shared characteristics, a sensible approach is to reference the description of the class.

References should be given where appropriate, but a DDD should not refer to documents that follow it in the ESA PSS-05-0 life cycle.

Part 1 of the DDD must be completed before any coding is started. The component design specification in Part 2 must be complete (i.e. no TBCs or TBDs) before coding is started.

5.6.1 DDD/Part 1 - General description

5.6.1.1 DDD/Part 1/1 Introduction

This section should describe the purpose and scope, and provide a glossary, list of references and document overview.

5.6.1.1.1 DDD/Part 1/1.1 Purpose (of the document)

This section should:

(1) describe the purpose of the particular DDD:

(2) specify the intended readership of the DDD.

 

ESA PSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

5.6.1.1.2 DDD/Pait 1/1.2 Scope (of the software)

This section should:

(1) identify the software products to be produced;

(2) explain what the proposed software will do (and will not do, if necessary):

(3) define relevant benefits, objectives, and goals as precisely as possible;

(4) be consistent with similar statements in higher-level specifications, if they exist.

5.6.1.1.3 DDD/Part 1/1.3 Definitions, acronyms and abbreviations

This section should define all terms, acronyms, and abbreviations used in the DDD.or refer to other documents where the definitions can be found.

5.6.1.1.4 DDD/Part 1/1.4 References

This section should list all the applicable and reference documents, identified by title, author and date. Each document should be marked as applicable or reference. If appropriate, report number, journal name and publishing organisation should be included.

5.6.1.1.5 DDD/Part 1/1.5 Overview (of the document)

This section should:

(1) describe what the rest of the DDD contains;

(2) explain how the DDD is organised.

5.6.1.2 DDD/Part 1/2 Project standards, conventions and procedures

5.6.1.2.1 DDD/Part 1/2.1 Design standards

These should usually reference methods carried over from the AD phase and only describe DD phase specific methods.

The Detailed Design Standard might need to be different if more than one method or programming language is involved: for example, if some Ρ language design and programming takes place in an Ada project.

 

ESAPSS-05-05 Issue 1 (May 1992) 61 THE DETAILED DESIGN DOCUMENT

5.6.1.2.2 DDD/Part 1/2.2 Documentation standards

This section should describe the format, style, and tools adopted by the project for DD and code documentation. Headers, footers, section formats and typefaces should be specified. They may be prepared as word processor template files, for automatic inclusion in all project documents. If the formats are new, they should be prototyped and reviewed (with users in the case of the SUM).

This section should contain the standard module header and contain instructions for its completion (see Section 2.3.9).

5.6.1.2.3 DDD/Part 1/2.3 Naming conventions

This section should explain all naming conventions used, and draw attention to any points a maintenance programmer would not expect. A table of the file types and the permitted names or extensions for each is recommended for quick reference. See the examples in Table 5.6.1.2.3 and Section 5.6.2.1.

File Type Name Extension
document “mnemonic” .DOC
Ada source code IDENTIFIER .ADA
Fortran source code IDENTIFIER .FOR
diagram “mnemonic” .PIC

Table 5.6.1.2.3 Names and extensions

Conventions for naming files, programs, modules, and possibly other structures such as variables and messages, should all be documented here.

5.6.1.2.4 DDD/Part 1/2.4 Programming standards

This section should define the project programming standards. Whatever languages or standards are chosen, the aim should be to create a convenient and easily usable method for writing good-quality software. Note especially the guidelines in Section 2.3.

 

62 ESA PSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

If the programming language is described in an ESA PSS-05 level 3 Guide, then the guidelines described in that document should be adopted. Additional restrictions on the use of the language may be imposed if necessary: such additions should be justified here.

When programming in any other language, a standard for its use should be written to provide guidance for programmers. This standard may be referenced or included here.

In general, the programming standard should define a consistent and uniform programming style. Specific points to cover are:

• modularity and structuring:

• headers and commenting;

• indenting and layout;

• library routines to be used:

• language constructs to use:

• language constructs to avoid.

5.6.1.2.5 DDD/Pait 1 /2.5 Software development tools

This section should list the tools chosen to assist software development. Normally the list will include:

• a CASE tool;

• a source code editor;

• a compiler;

• a debugger;

• a linker;

• a configuration manager / builder;

• a word processor for documentation:

• a tool for drawing diagrams.

Many projects will also use a configuration management system to store configuration items, such as documentation, code and test data.

Prototyping projects might make use of an interpretative toot, such as an incremental compiler/interpreter/debugger.

Other tools that may be helpful to many projects include:

• static analysers;

• dynamic analysers;

 

ESAPSS-05-05 Issue 1 (May 1992) 63 THE DETAILED DESIGN DOCUMENT

• network and data communication tools:

• graphics packages:

• statistics and mathematical packages.

Real-time and embedded systems may require special development tools, including:

• cross-compilers;

• diagnostic, logging, and probe tools.

5.6.2 DDD/Part 2 - Component design specifications

The descriptions of the components should be laid out hierarchically. There should be subsections dealing with the following aspects of each component:

n Component identifier

n.l Type

n.2 Purpose

n.3 Function

n.4 Subordinates

n.5 Dependencies

n.6 Interfaces

n.7 Resources

n.8 References

n.9 Processing

n.10 Data

The number 'n' should relate to the place of the component in the hierarchy.

5.6.2.1 DDD/Part 2/5.n Component Identifier

Each component should have a unique identifier (SCM06) for effective configuration management. The component should be named according to the rules of the programming language or operating system to be used. Where possible, a hierarchical naming scheme should be used that identifies the parent of the component (e.g. ParentName_ChildName)

The identifier should reflect the purpose and function of the component and be brief yet meaningful. If abbreviation is necessary, abbreviations should be applied consistently and without ambiguity. Abbreviations should be documented. Component identifiers should be

 

64 ESAPSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

mutually consistent (e.g. if there is a routine called READ_RECORD then one might expect a routine called WRITE.RECORD, not RECORD_WRITING_ROUTINE).

A naming style that clearly distinguishes objects of different classes is good programming practice. In Pascal, for instance, it is traditional to use upper case for user-defined types, mixed case for modules, and lower case for variables, giving the following appearance:

• procedure Count_Chars: {a module}

• type SMALLJNT = 1 ..255; {a type}

• var count: SMALLJNT; (a variable}

Other styles may be appropriate in other languages. The naming style should be consistent throughout a project. It is wise to avoid styles that might confuse maintenance programmers accustomed to standard industrial practices.

5.6.2.1.1 DDD/Part2/5.n.1Type

Component type should be defined by staling its logical and physical characteristics. The logical characteristics should be defined by stating the package, library or class that the component belongs to. The physical characteristics should be defined by stating the type of component, using the implementation terminology (e.g. task, subroutine, subprogram, package, file).

The contents of some component-description sections depend on the component type. For this guide the categories: executable (i.e. contains computer instructions) or non-executable (i.e. contains only data) are used.

5.6.2.1.2 DDD/Part 2/5.Ο.2 Purpose

The purpose of a component should be defined by tracing it to the software requirements that it implements.

Backward traceability depends upon each component description explicitly referencing the requirements that justify its existence.

5.6.2.1.3 DDD/Part 2/5.Ο.Η Function

The function of a component must be defined in the DDD. This should be done by stating what the component does.

 

ESAPSS-05-05 Issue 1 (May 1992) 65 THE DETAILED DESIGN DOCUMENT

The function description depends upon the component type. Therefore it may be a description of the:

• process;

• information stored or transmitted.

Process descriptions may use such techniques as Structured English, Precondition-Postcondition specifications and State-Transition Diagrams.

5.6.2.1.4 DDD/Part 2/5.Ο.4 Subordinates

The subordinates of a component should be defined by listing the immediate children. The subordinates of a program are the subroutines that are 'called by' it. The subordinates of a database could be the files that 'compose' it. The subordinates of an object are the objects that are 'used by' it.

5.6.2.1.5 DDD/Part 2/5.Ο.5 Dependencies

The dependencies of a component should be defined by listing the constraints placed upon its use by other components. For example:

• 'what operations must have taken place before this component is called?'

• 'what operations are excluded while this operation is taking place?'

• 'what operations have to be carried out after this one?'.

5.6.2.1.6 DDD/Part 2/5.n.6 Interfaces

Both control flow and data flow aspects of each interface need to be specified in the DDD for each 'executable' component. Data aspects of 'non-executable' components should be defined in Subsection 10.

The control flow to and from a component should be defined in terms of how execution of the component is to be started (e.g. subroutine call) and how it is to be terminated (e.g. return). This may be implicit in the definition of the type of component, and a description may not be necessary. Control flows may also take place during execution (e.g. interrupt) and these should be defined, if they exist.

The data flow input to and output from each component must be detailed in the DDD. Data structures should be identified that:

• are associated with the control flow (e.g. call argument list);

• interface components through common data areas and files.

 

66 ESA PSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

One component's input may be another's output and to avoid duplication of interface definitions, specific data components should be defined and described separately (e.g. files, messages). The interface definition should only identify the data component and not define its contents.

The interfaces of a component should be defined by explaining 'how' the component interacts with the components that use it. This can be done by describing the mechanisms for:

• invoking or interrupting the component's execution;

• communicating through parameters, common data areas or messages:

If a component interfaces to components in the same system, the interface description should be defined in the DDD (if not already in the ADD). If a component interfaces to components in other systems, the interface description should be defined in an Interface Control Document (ICD).

5.6.2.1.7 DDD/Part 2/5.n.7 Resources

The resources a component requires should be defined by itemising what the component needs from its environment to perform its function. Items that are part of the component interface are excluded. Examples of resources that might be needed by a component are displays, printers and buffers.

5.6.2.1.8 DDD/Part 2/5.Ο.8 References

Explicit references should be inserted where a component description uses or implies material from another document.

5.6.2.1.9 DDD/Part 2/5.Ο.9 Processing

The DDD should describe in detail how processing is carried out. Algorithms that are fully described elsewhere may be summarised briefly, provided their sources are properly referenced.

The processing a component needs to do should be defined by defining the control and data flow within it. For some kinds of component (e.g. files) there is no such flow. In practice it is often difficult to separate the description of function from the description of processing. Therefore a detailed description of function can compensate

 

ESAPSS-05-05 Issue 1 (May 1992) 67 THE DETAILED DESIGN DOCUMENT

for a lack of detail in the specification of the processing. Techniques of process specification more oriented towards software design are Program Design Language, Pseudo-code and Flow Charts.

Software constraints may specify that the processing be performed using a particular algorithm (which should be stated or referenced).

5.6.2.1.10 DDD/Part 2/5.Ο.10 Data

The data internal to a component should be defined. The amount of detail required depends strongly on the type of component. The logical and physical data structure of files that interface components should have been defined in the DDD (files and data structures that interface major components will have been defined in the ADD). The data structures internal to a program or subroutine should also be specified (contrast the ADD, where it is omitted).

Data structure definitions must include the:

• description of each element (e.g. name, type, dimension);

• relationships between the elements (i.e. the structure);

• range of possible values of each element;

• initial values of each element.

5.6.3 DDD/Appendix A: Source code listings

This section must contain either:

• listings of the source code, or

• a configuration item list identifying where the source code can be found (DD12).

5.6.4 DDD/Appendix B: Software requirements traceability matrix

This section should contain a table that summarises how each software requirement has been met in the DDD (DD16). The tabular format permits one-to-one and one-to-many relationships to be shown. A template is provided in Appendix D.

 

68 ESA PSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN DOCUMENT

This page is intentionally left blank.

 

ESA PSS-05-05 Issue 1 (May 1992) 69 THE SOFTWARE USER MANUAL


Date: 2016-01-03; view: 732


<== previous page | next page ==>
Language-sensitive editors | Natural-language and speech interface systems
doclecture.net - lectures - 2014-2024 year. Copyright infringement or personal data (0.019 sec.)