3 GENERAL CODING STANDARD

The rules and guidelines in this section apply to all applications programming irrespective of what ‘software environment’ they run under. They fall into four groups – language, design, quality and presentation.

3.1 Language

The only permitted dialect of Fortran is ANSI X3.9-1978 (known as Fortran 77) plus certain US Department of Defense extensions and – in a few cases only – some extensions provided in DEC and several other proprietary Fortrans.

Discriminating Fortran users were disappointed with the 1978 standard, which failed to contain many expected improvements. Experience with preprocessors (RATFOR for example) had shown the feasibility of turning Fortran into a much better language with a minimum of disruption; unfortunately, many features which could easily have been added to the language weren’t. DEC Fortran, however, does have a few of these features, and it was decided that certain of these should be permitted within the Starlink standard. The rationale was (i) it would not be hard to eliminate these extensions manually if necessary, (ii) they have become almost universal, and (iii) similar facilities will be part of later Fortran standards. Note that anyone wishing to adhere more rigidly to the Fortran 77 standard is permitted to do so. The latest version of Fortran, called Fortran 90, contains many improvements over Fortran 77 and almost eliminates the need to use any platform-specific features. Extra facilities not available in existing Fortran 77 implementations (for example the processing of whole arrays as primitive data items) are also available. The Fortran 90 standard identifies certain features as ‘deprecated’ or ‘obsolescent’, candidates for deletion in future standards; almost all of these are already prohibited by the Starlink standard. Fortran 90 compilers are not presently provided on Starlink but will be in due course.

The following extensions to the Fortran 77 standard are permitted within Starlink:

IMPLICIT NONE, END DO, DO WHILE and INCLUDE are all in Fortran 90. See Section 5, Writing Portable Programs, for detailed advice on INCLUDE statements.

Here are some examples of features which are part of neither the Fortran 77 standard nor the Starlink standard, and are to be avoided:

Certain other non-standard features are dealt with later sections. The DEC Fortran manual has all extensions to the ANSI standard printed in blue, and these features should be avoided unless expressly sanctioned in the Starlink standard. If an extension has to be used for any reason (because the required result simply cannot be obtained any other way) this should be highlighted with comments. If you are unsure about whether your program conforms to the Fortran 77 standard, try compiling it with the /STANDARD qualifier (on VMS systems).

Notes:

(1)

INTEGER*2 and BYTE data types may be used where they are essential to deal with input data sets containing 8 or 16 bit values.

(2)

Many programmers refuse point-blank to stick to 6 character names, and some even like using whole sentences with underscores between the words. Opinions vary on whether long names help readability all that much, but what is certain is that several computer systems of considerable potential importance to UK astronomers do not support long names (for example some mainframes, certain attached processors, some workstations). Some computers accept names longer than 6 characters but only a little longer; others accept long names but ignore all but the first n characters.

Though names internal to a Starlink program must be no more than 6 characters long, the use of names of more than 6 characters is permissible (and indeed strongly encouraged) in the case of program unit and labelled COMMON block names, in order to reduce the chances of name clashes between different facilities (especially the C run-time library). Such names should be constructed by prefixing the name proper, which must be no more than 6 characters long, with a facility name of the form ‘FAC_’. An example is SGS_OPEN: the facility name is SGS and the name of the routine OPEN. For the utmost portability, it is wise to limit the name proper to 5 characters rather than the full 6; thus SGS_ZSIZE can readily be preprocessed to SZSIZE (for example) if merely dropping the SGS_ gives name clashes. Within a given package, the name proper should be unique even if different facility names are being used. A further Starlink convention is that routines called only internally within a package are given names prefixed with ‘FAC1_’ rather than simply ‘FAC_’. Application programmers should never use existing facility names (see Appendix A) unless contributing solicited and debugged software for inclusion in the facility concerned.

Fortran 90 allows names of up to 32 characters.

(3)

Use of bit manipulation routines will be unavoidable in instrument specific processing but is prohibited for general applications. (Note that Fortran 90 contains bit-manipulation facilities.)

(4)

Certain VAX extensions to the OPEN and INQUIRE statements overcome serious omissions from the Fortran 77 standard and may be used if necessary:

• READONLY
• CARRIAGECONTROL=‘LIST’
• ACCESS=‘APPEND’ (worth avoiding)

Highlight these VAX-specific items with comments, and use them only in short routines which can be re-coded for other platforms.

(5)

In FORMAT statements, O (octal) and Z (hexadecimal) edit descriptors may be required for the early stages of instrument specific processing, but must not be used otherwise. Q (number of characters input) and $ (suppress carriage return) should be avoided. Sometimes they have to be used, typically at just one place in an application, and when this happens they should be prominently commented as VAX-specific and preferably isolated inside a short routine which can be re-coded for other platforms.

(6)

The DEC Fortran %VAL etc. may be required to interface to ‘software environment’ routines. (ADAM is one such software environment – see section 4.) They should not be used for any other purpose.

Though a few other characters are sufficiently common for trouble to be unlikely it is best to avoid them even in comments as they may appear different on different terminals and printers – hash and pounds sign are particular examples of this. Backslash is best avoided because it has a special meaning in almost all Unix Fortrans. Applications should not depend on the presence of nonstandard characters – stick to the Fortran 77 set.

An exception is made for lowercase letters a-z, which are (a) permitted in program source code, and (b) encouraged in output messages. The recommended style is to use upper- and lowercase freely in comments but to use uppercase in the Fortran proper. If you must use lowercase characters in Fortran statements, it is important to be consistent, not just to make the code easier to read, but also because the Fortran compilers on some Unix systems regard upper- and lowercase characters as different (so N and n would be different entities for example).

The character set allowed by Fortran 90 includes _ ! " % & ; < > ? [ ].

Take care with collating sequence. The letters A-Z appear in the expected order, but you cannot assume that they are contiguous in the collating sequence. Similar remarks apply to 0-9. Do not assume that the numbers appear before the letters. Assume nothing about the collating sequence of punctuation characters, except that blank comes before both the letters and the numbers.

is prohibited. It offers even more opportunity for unstructured programming than the discredited GO TO and, moreover, doesn’t read naturally in English. (The arithmetic IF is a fossil of one of the machine instructions on the computer for which Fortran was first devised, the IBM 704.)

STOP produces a message that is usually uninformative and is incompatible with software environments. It is also redundant – the main program’s END statement causes program termination.

RETURN is redundant – a subprogram’s END statement returns to the caller.

The key reason for prohibiting STOP and RETURN is to force the programmer to have one exit point only per routine, at the end, to aid debugging. This complements the ban on multiple entry points (and hence on alternate RETURN) in satisfying structured programming requirements.

Note that the ban on ENTRY and RETURN means that multiple ENTRYs and RETURNs are similarly prohibited.

must be used, rather than:

The rules in the ANSI standard concerning SAVE are rather complex and no further attempt will be made to summarize them here.

The use of a consistent naming scheme to indicate type, though unfashionable, is worth considering. The standard Fortran convention of an initial I-N can be used to highlight integers, and where REAL and DOUBLE PRECISION variables are being mixed it can be helpful to reserve initial D for the latter. CHARACTER, LOGICAL and COMPLEX entities are more rarely confused and there is usually less need for naming conventions.

Arrays appearing in COMMON must have their type and dimensions declared in separate statements which precede the COMMON declaration. For example:

The types of subprogram arguments must be specified explicitly.

Avoid list-directed I/O, which may give different results on different machines. There are library routines for input and output conversions (see sla_DFLTIN in SLALIB for example); use these.

In many ‘software environments’ (ADAM for example – see section 4), Fortran I/O to the terminal is not permitted, and any Fortran I/O to files should be done in accordance with any special rules of the software environment concerned.

The various ‘software environments’ usually have ways of supplying such logical unit numbers from a pool, and this is recommended.

rather than:

Changing from one number format to another is a very significant event in an algorithm and should be clearly expressed. Great circumspection should be employed when deciding where such conversions should occur.

is not permitted.

• Do not use EQUIVALENCE to ‘extend’ an array.
• Do not EQUIVALENCE anything in COMMON.
• Do not EQUIVALENCE entities of different data types.

3.2 Design

Programs written using structured programming techniques are built out of three basic elements: (a) processing sequences, (b) decisions, and (c) loops. Each of these three elements has only one entry point (at the top) and only one exit (at the bottom), and its relationship with the data it uses is clearly defined. The whole program consists of a hierarchy of these elements. In Fortran 77, (a) is just a series of statements, (b) is an IF THEN ELSE construct and (c) is one of the DO constructs. The most conspicuous feature of structured programs is the absence of (or, depending on the suitability of the programming language being used, the relative absence of) GO TO statements. Such programs are incomparably easier to follow than ones containing tangled GO TO logic, but may be harder to write, especially if you have not completely grasped what you are trying to do before you start coding.

To conform to the Starlink standard, a program must not show signs of having been written ‘bottom-up’, or having ‘grown like Topsy’. It can be a good plan to begin by writing the program in a ‘structured English’ pseudo-language; this can then become, as comments, part of the program.

The SPAG utility (SUN/63) can re-arrange GOTO- and arithmetic-IF-infested code into block-structured form, and this is a good first step when working up old code into a maintainable form.

If you are prepared to use the non-ANSI-standard DO WHILE, you can write a loop which includes tests for exit and repeat conditions, without using the GO TO:

The names of entities in COMMON must not change from one program unit to another; the use of dummies is discouraged.

All COMMON block source should be stored in separate files from the rest of the source, and be inserted using the INCLUDE statement.

Blank common must not be used – only labelled common (with a fac_ prefix to the name, as described in rule 1 note 2).

Note that the Fortran 77 standard does not permit initialization of common blocks via DATA statements in main programs or normal subprograms; BLOCK DATA must be used. (Avoid potential linking difficulties when using BLOCK DATA by referring to the name of the BLOCK DATA module in an EXTERNAL statement in at least one of the subprograms that makes use of the relevant COMMON block.)

FORCHECK (see SUN/73) will detect all of these conditions.

When soliciting a file or device name from the user, make no assumptions about its format and pass on the string received (to an OPEN statement typically) without altering it or trying to deduce things from it.

3.3 Quality

If a size is required in more than one program unit, it should be declared in an INCLUDE file.

There are only two exemptions permitted:

• Subprograms called exclusively by programs which can guarantee to present valid arguments.
• Subprograms which explicitly put the onus of validation onto the caller to achieve some real efficiency advantage.

Applications running under a ‘software environment’ (for example ADAM – see Section 4) should adopt the error reporting strategy provided by that environment. The ERR_ and MSG_ packages (SUN/104) provide error reporting that works both in ADAM-based and freestanding programs. These packages enable subprograms to report errors in detail while still allowing higher levels to decide whether or not messages will actually appear on the user’s screen.

(But see remarks about bad-pixel handling in ADAM applications – section 4.)

Note that the Fortran 77 standard prohibits use of the same actual argument more than once when calling a subprogram which gives one of the arguments concerned a new value. Thus a subroutine P(A,B,R), which computes some function of A and B and finally returns it in R, must not be called with arguments (X,Y,X) even though this technique happens usually to work in VAX Fortran (for example).

Do not include in a package copies or slight variants of Starlink routines in an attempt to make the package self-contained. Assume the availability of the required Starlink library, and if the package has to be run on an installation which does not have the Starlink software collection make proper arrangements with the Starlink Software Librarian to have the up-to-date libraries sent there.

Avoid using the Run-Time-Library routines available on VAX/VMS and other platforms. Many of the facilities included in these libraries are also provided by POSIX, an industry-standard Portable Operating System Interface. Fortran-callable versions of many of these routines are provided in the Starlink PSX library.

Many of the libraries which form part of the ADAM Software Environment (see Section 4) are available in two forms: an ADAM version and a free-standing version. Programmers are strongly recommended to use these libraries even where there is no immediate intention of running under ADAM.

3.4 Presentation

All program units must have sensible and self explanatory names, as far as is possible given the limitations imposed by the 6 character or fac_ + 5 character rule (see rule 1 note 2).

To enable automatic recognition, each block of prologue comments must begin with a comment which starts $\ast +$ and ends with a comment which starts $\ast -$. Elsewhere in the program, do not have any statements with $+$ or $-$ in the second column.

Main programs must have a prologue which says what files will be read or written, and gives the I/O unit identifiers used (numbers or symbols).

Subprogram prologues must list all the arguments, clearly describing their function, type (unless obvious), units (where applicable) and any special properties (e.g. whether an array). The words ‘given’ and ‘returned’ are recommended for direction, rather than ‘input’, ‘output’, ‘source’, ‘destination’ and other possibly ambiguous terms. Access to COMMON blocks should be treated similarly, with every item referenced fully described.

It is recommended that the names of all subprograms called (except the Fortran 77 intrinsic functions) be given in the prologue. It is extremely important that all the information given in the prologue is accurate and up to date. Prologues can be automatically extracted from source held in text libraries by using the LIBPRE facility (see SUN/8).

Example:

Note, however, that much of the freedom implied by the above recommendations may not be available to programs which conform to the documentation standards of a particular ‘software environment’, especially if automatic documentation facilities are involved. For details of the prologue requirements of the ADAM software environment, see section 4.

Comments beginning in column 7 are strongly discouraged, even if preceded by C***** and the like.

The comments, which should in general precede the code they describe:

• must accurately reflect the behaviour of the program;
• must be detailed without merely stating the obvious;
• must not be cryptic – ‘clues’ are not enough;
• must be in English, without spelling or grammatical errors;
• must not contain attempts at humour, meretricious phraseology, catchwords, superfluous pleasantries, private jargon and clever abbreviations.

There should be no need for elaborate and unsightly ‘revision-flag’ schemes except, perhaps, during debugging or where software that runs on more than one machine has machine specific inclusions.

Using 1,2,3 … for successive lines is specifically discouraged as it leads to annoying editing problems (and, after all, protection against shuffling is no more necessary than for any other region of the program).

A suggested scheme is as follows. The normal starting columns for comments and code should be 5 and 7 respectively. For each block between a DO and END DO, or between IF, ELSE IF, ELSE and END IF, both comments and code should be indented a further 3 columns. Blank lines should be used freely to improve presentation further.

This scheme is used in the following example. This is, of course, only one acceptable layout, and tastes vary.