Appendix D5 Production Control & Review od Software.pdf

Appendix D5

Guideline for the Production, Control, and Review of Software

1. Introduction

This is a Guideline for the Production, control, and review of software. It also includes general guidance on

coding practices.

2. Scope

This Guideline should be use d to define procedures and standards for software development and review.

The guidance included is equally applicable to development projects, to suppliers developing a product, and

to users developing software.

3. Guidelines

3.1 Software Production

3.1.1

General

Each project should indicate the program coding standards, directory structure standards, and file naming

conventions to be followed. These should be documented, and referenced in the Quality and Project Plan.

Where command files are necessary for build management, including compilation of source modules or

linking of object modules, these also should be controlled in accordance with documented procedures.

Once programme code has been successfully compiled it should be subject to a documented review, as

described in Section 3.2 of this Appendix. The review should take place before acceptance testing of the

software commences.

Software should be subject to Configuration Management.

Any Software development tools used should be assessed for suitability and fitness for purpose, and this

assessment documented.

Guidelines for Categories of Software and Hardware and for Configuration Management are given in

Appendix M4 and Appendix M9, respectively.

3.1.2

Software module identification

Each software module should have at least the following information in the module header:

•

Module name

•

Means of reference to controlling design specification

•

Constituent source file names

•

Module version number

•

Project name and number (if applicable)

Brief description of the module

•

Any specific command files required to compile and build the module

•

Change History: this should consist of the following information for each change:

Change Request number

New version number

Dates change(s) made

Initial of person(s) making change(s)

Source code file(s) affected

3.1.3

Software Module Traceability

All software module changes should be clearly identified in the source code files.

Additions should be identified by the use of commentary that references the relevant Change Request

number.

Deletions should be identified either by:

Commenting out the code and indicating the deletion by referencing the relevant Change Request

(for minor changes, e.g., a few lines of code deleted)

•

Deleting the code and indicating the deletion by referencing the relevant Change Request (for major

changes, e.g., when a significant amount of code is removed)

3.1.4

General Design and Documentation Principles

Software should be based on a documented, reviewed, well-structured design, and developed following

established programming practices. Such that it is:

•

Reliable

•

Robust

•

Maintainable

Capable of handling error conditions

•

Modular in structure

•

Well laid out and commented

3.1.5

Reliability and Error Recovery

The software should either recover from incorrect data or incorrect operation of any equipment, or fail in a

safe and predictable manner. ‘Defensive’ coding techniques should be employed. For example, input values

should be checked, and subroutines should check that the values of the received parameters are within

range. In the event of a failure, a safe, documented error recovery or a controlled shutdown should be

performed, with an informative error message.

3.1.6

Maintainability

Software should be written in a way that a competent programmer (other than the software author) would be

able to maintain and enhance the software if required. The code should be clearly laid out and commented.

The following should be considered:

•

Breaking down procedures into logically distinct blocks, each performing just one step in the

processing sequence or logic. Each block should normally be preceded by a comment.

Only one action per line of code (except for cases such as multiple initializations)

•

Indentation of code should be used to indicate different levels in the logic, e.g., for ‘DO’,‘WHILE’,

‘UNTIL’ loops, and ‘IF…THEN…ELSE’ conditional blocks

•

Code should be vertically aligned where appropriate, e.g., declarations, sequences of assignments

(‘=’ signs), trailing comments

•

Brackets should be used in logical or arithmetic expressions, even if not strictly necessary, if they

make the expression clearer

•

Consideration should be given to readability, both on-screen, and in printed form

•

Limiting the size and complexity of procedures (using appropriate measures such as function points,

or lines of code)

Avoiding ‘clever’ code, which may be very difficult to understand or maintain

•

3.1.7

Modular Structure

Individual modules should normally perform a single, easily identifiable function. Modules should be distinct

and as logically separate as possible. The use of subroutine or function side effects should be avoided.

3.1.8

Removal of ‘Dead’ Code

This is code that cannot be executed due to the logic of the program, and should be removed. It is usually a

symptom of poor maintenance, and may have been left over by accident from development or code changes.

Code that has been included for purposes of testing or for later diagnosis during support work, and which can

be configured ‘on’ or ‘off’, is not regarded as dead code. Any such code should be clearly documented.

If the code is ‘configurable’ or ‘general purpose’ code that may be used in many different projects, each with

different configurations of options, the unused options should not be removed. The software review and the

testing processes, however, should demonstrate that the correct options have been selected and that they

work, and that the deselected options have been correctly deselected and do not function.

Code that has been properly commented-out during the operational change process is not regarded as dead

code and may be an appropriate technique for minor changes during the operational phase. The clean up of

comment -out code prior to formal testing of the initial and subsequent major releases of software should be

considered, as an aid to code maintenance.

3.1.9

Variable Naming and Initialization

The names of variables should be meaningful to programmers reading the code. Documented, language

specific, naming conventions should be established.

All variables should be declared, even in languages that do not require this, and in such languages the

compiler check for undeclared variables should be switched on.

Each variable should be used only for one purpose.

Loop counters may be reused, provided each use is independent, and provided that they are used for no

other purpose. Loop counters with the same name should not be nested.

All variables should be initialised before they are used. Care must be taken to declare variables of the

correct type and precision (or size) for their intended use,especially where the language permits similar data

types of different precision to be used. The declaration and initialization of variables that are not

subsequently used should be avoided.

3.1.10 Labels and Branching

The code should be written using structured programming techniques to the extent that the programming

language allows it, and this should ensure that the use of labels is minimized. For any labels that remain,

their names should be meaningful. In programming languages that allow only numerical labels, the labels

should have increasing numerical value within the code for a module.

In languages that allow (but do not require) declaration of labels, all labels should be declared. Unused

labels should be removed. Branches to labels should, as far as possible, be forward.

Branches into ‘DO, ‘DO WHILE’ or ‘DO…UNTIL’ loops, or ‘IF…THEN…ELSE’ blocks, or ‘CASE’ blocks,

should always be avoided. Branching out of such loops should only be used in necessary and defined

circumstances, e.g., for error and exception handling. The impact on the integrity of data, such as that

contained in counters and pointers, should be considered whenever branching.

3.1.11 Cross- reference Tables

Before code is released for System Acceptance Testing, a cross-reference table of symbols (i.e., variables,

procedures, labels) should be generated for each module (if the language compiler or other utility provides

this option), and static analysis checks should be made for all variables to ensure that they are declared,

initialised, and used correctly. The following checks should be made for each symbol listed (as appropriate):

Are all symbols used?

•

Are all variables initialised or set before they are used?

•

Is there any potential confusion between global and local variables with the same name?

•

Are all variables declared?

•

Are all procedures called somewhere within the code?

•

3.1.12 Switches, CASE statements, and Multi -way Branches

Multiple options should include a default option for all values outside of the expected range. The processing

for each option should normally exit properly to the next step in the process, and not ‘run on’ into the next

coded option. If the code is intended to ‘run on’ into the next option, a comment should be included to

explain the reason why. All exits from a procedure should be through a single exit point, normally at the end.

3.1.13

Comparing Values

Integer and string or character expressions can be directly compared for equality. The use of equality

comparisons between real expressions should be carefully considered, bearing in mind the constraints of the

programming language, operating system environment, and the hardware architecture. Attention should be

given to comparisons with zero, and the use of pre-defined tolerances.

3.1.13 Error-prone Language Features

The following features of some languages have been found in various studies of software reliability to be

potentially error prone, and should be used with great care, following language specific conventions and best

practices.

•

GOTO, Assigned GOTO, and GOSUB

•

Floating-point numbers

•

Pointers

•

Parallelism

•

Recursion

•

Interrupts

•

Dynamic allocation of memory

3.1.14 Compiler Switches

Most compilers allow options to be switched on and off during various compile time and run time checks,

e.g., underflow, overflow, array bound checking, range checking. Compile time checks should be switched

on for all compilations, and all run-time checks enabled, at least during software development and initial

testing, and preferably through to final testing and operation.

If it is not possible to leave them switched on for the final version, because of programme size or speed

limitations, tests should be performed both with and without run time checks. For GxP critical software, the

benefits, and potential risks of switching on code optimisation should be considered, and the decision

documented.

3.2 Source Code Review

Source Code reviews have two objectives:

To ensure that programming standards, such as those described in Section 3.1 of this Appendix, are

consistently and correctly applied

•

To ensure that the code is written in accordance with the design specifications

The review aims to ensure that the code is fit to enter testing (module, integration or system tests), and that

the code can be effectively and efficiently maintained during the period of use of the application.

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: