Documentation of variables

Programmers should document the meaning of all variables. Documentation should be integrated with the code (e.g. as a comment to the declaration). The possible values of variables should either be stated in the variable declaration (as in Ada), or documented.

Names of variables

Finding meaningful names for variables exercises the imagination of every programmer, but it is effort well worth spending. Names should reflect the purpose of the variable. Natural language words should be used wherever possible. Abbreviations and acronyms, if used, should be defined, perhaps as part of the comment to a variable's declaration.

Similar names should be avoided so that a single typing error in the name of a variable does not identify another variable. Another reason not to use similar names is to avoid ambiguity.

Mixing data types

Some programming languages prevent the mixing of data types by the strong type checking feature (e.g. Ada). Mixing data types in expressions should always be avoided, even if the programming language allows it (e.g. FORTRAN). Examples of mixing data types include:

• mixing data types in expressions;

• mismatching data types in an argument list;

• equivalencing different data types.

Temporary variables

The temptation to define temporary variables to optimise code should be avoided. Although the use of temporary variables can simplify a statement, more statements are required, and more variables have to be declared. The net effect is that the module as a whole appears more complex.

ESAPSS-05-05 Issue 1 (May 1992) 17 THE DETAILED DESIGN AND PRODUCTION PHASE

Parentheses

Parentheses should be used in programming language expressions to avoid ambiguity, and to help the reader identify the sequences of operations to be performed. They should not be used solely to override the precedence rules of the language.

Layout and presentation

The layout of the code should allow the control logic to be easily appreciated. The usual technique is to separate blocks of sequential code from other statements by blank lines, and to indent statements in condition or iteration blocks. Statements that begin and end sequence, iteration and condition constructs should be aligned vertically (e.g. BEGIN... END, DO... ENDDO, and IF... ELSEIF... ELSE... ENDIF). Long statements should be broken and continued on the next line at a clause in the logic, not at the end of the line. There should never be more than one statement on a tine.

Comments

Comments increase understandability, but they are no substitute for well-designed, well-presented and intelligible code. Comments should be used to explain difficult or unusual parts of the code. Trivial comments should be avoided.

PDL statements and pseudo-code may be preserved in the code as comments to help reviewers. Comments should be clearly distinguishable from code. It is not adequate only to use a language keyword: comments should be well separated from code by means of blank lines, and perhaps written in mixed case (if upper case is used for the code).

Diagnostic code

Diagnostic code is often inserted into a module to:

• make assertions about the state of the program;

• display the contents of variables.

Care should be taken to prevent diagnostic code obscuring the module logic. There is often a temptation to remove diagnostic code to present a clean 'final' version of the source code. However routine diagnostic code that allows verification of correct execution can be invaluable in the maintenance phase. It is therefore recommended that

18 ESAPSS-05-05 Issue 1 (May 1992) THE DETAILED DESIGN AND PRODUCTION PHASE

routine diagnostic code be commented out or conditionally compiled (e.g. included as 'debug lines'). Ad hoc diagnostic code added to help discover the cause of a particular problem should be removed after the problem has been solved.

Date: 2016-01-03; view: 755