General requirements

  With respect to the program layout the following rules should be applied

• In case of nesting indent three positions.
• Subparts in subroutines must be separated by comment lines with a short description of the contents.
• Use an empty line before and after each comment part in the code.
• Never use tabs; it causes problems in case of exports to other computers.
• The first line in a comment should start with three minus signs, followed by a space and then the comment text. The first minus sign must be placed at the indent position. For example:

       if ( xxx ) then
  
  c    --- text
  
          statement
  
       else
  
  c    --- text
  
          statement
  
       end if
  

The layout of a program or subroutine is standard. The following rules with respect to contents and sequence should be applied.

1. module statement (PROGRAM, SUBROUTINE, FUNCTION )
2. Comment line starting with a c followed by a space and then 70 equals signs.
3. Comment block consisting of
   • Name programmer
   • Version number followed by date and if necessary comment
   • Version numbers of modifications with date, followed by a short description of the modification and the reason. (This comment may also contain the name of the author of the changes)
   • Copyright
   • Comment block separator

   The version number consists of a sequence number followed by a dot and another sequence number. The first number starts with 1, the second one with 0. In case of a small change, the second one is updated, in case of an essential change it is necessary to update the first sequence number and reset the second one to 0.
   The version numbers must be given in reversed order, i.e. last version number first.
   The comment block separator consists of a line with a c, a line with a c followed by a space and 70 times the sign, and again a line with a c.

4. Comment block consisting of
   • A c followed by a number of spaces followed by the word DESCRIPTION (in capitals)
   • A line with a c, followed by two lines containing a short description of the subroutine. These two lines may be followed by additional information about the description, as long as the first two lines give sufficient information.
   • Comment block separator

   Subroutines which are sensitive to machine accuracy should contain a warning in the description.
   The reason that the first two lines should contain a complete documentation is that some tools are available that generate automatically the system documentation from the source files. These tools only use the first lines of the description.

5. Comment block consisting of
   • A c followed by a number of spaces followed by the word KEYWORDS (in capitals)
   • A line with a c, followed by lines containing one keyword each.
   • Comment block separator

   Keywords should be written with small letters and without space. In order to improve the readability it is allowed to use underscores.

6. A block consisting of
   • A c followed by a number of spaces followed by the words
     INPUT / OUTPUT PARAMETERS (in capitals)
   • A line with a c, followed by the actual declaration of the input and output parameters. The first declaration should be IMPLICIT NONE.
   • An empty line followed by a lexicographic ordered description of the input and output parameters provided with an i and or an o.
   • Comment block separator

7. A block consisting of
   • A c followed by a number of spaces followed by the words COMMON BLOCKS (in capitals)
   • A line with a c, followed by the actual declaration and description of the commons.
   • Comment block separator

   Each common should contain:

   • Declaration of variables
   • Declaration of common block
   • Save statement
   • Comment block with
     name common
     function common
     description of parameters in common in lexicographic sequence

   It is advised to replace each common by an include statement, except when the software is exported to other computers.

8. A block consisting of
   • A c followed by a number of spaces followed by the words LOCAL PARAMETERS (in capitals)
   • A line with a c, followed by the actual declaration and description of the local parameters.
   • Comment block separator

   The description of the variables should be in lexicographic order.

9. A comment block consisting of
   • A c followed by a number of spaces followed by the words SUBROUTINES CALLED (in capitals)
   • A line with a c, followed by the actual lexicographic description of all the (function) subroutines used in the subroutine.
   • Comment block separator

   If an external subroutine is present in a special library, it is also necessary to indicate the source of this subroutine for example (IMSL).

10. A comment block consisting of
    • A c followed by a number of spaces followed by the words I/O (in capitals)
    • A line with a c, followed by the description of the input and output through files, including logical unit numbers and files.
    • Comment block separator

11. A comment block consisting of
    • A c followed by a number of spaces followed by the words ERROR MESSAGES (in capitals)
    • A line with a c, followed by the description of the error messages.
    • Comment block separator

12. A comment block consisting of
    • A c followed by a number of spaces followed by the words PSEUDO CODE (in capitals)
    • A line with a c, followed by the description of the subroutine in the form of a pseudo code.
    • Comment line starting with a c followed by a space and then 70 equals signs.

    For some remarks concerning the pseudo code we refer to Section 3.2.

13. Program text

If necessary, it is also allowed to have a separate block DATA STATEMENTS.
The sequence of the various blocks given above is fixed, but the blocks INPUT OUTPUT PARAMETERS, COMMON BLOCKS may be mutually interchanged, if the common block contains parameters necessary for the declaration of the input or output parameters.
The continuation mark can be chosen freely, however, a plus sign (+) is recommended.
In Section3.3 an example of a subroutine layout is given. Only this layout is allowed in ISNaS and SEPRAN subroutines. Tools to check and even to produce a part of the layout are treated in Chapter 5.