\documentclass[12pt]{book}
\usepackage{html,a4wide}
\usepackage[british]{babel}
\newcommand{\hl}[1]{\htmladdnormallink{{\it #1}}{#1}}
\begin{document}
\pagenumbering{roman}
\pagestyle{empty}

\begin{center}
{\Huge\bf SWAN}
\end{center}
\vspace{2cm}
\begin{center}
{\Large\bf PROGRAMMING RULES}
\end{center}
\vfill
\begin{center}
{\Large\bf Version 1.3}
\end{center}

\cleardoublepage

\noindent
{\Large\bf SWAN PROGRAMMING RULES}

\vfill

\begin{table}[htb]
\begin{tabular}{lcl}
by           &:& The SWAN team \\
             & & \\
mail address &:& Delft University of Technology \\
             & & Faculty of Civil Engineering and Geosciences \\
             & & Environmental Fluid Mechanics Section \\
             & & P.O. Box 5048 \\
             & & 2600 GA Delft \\
             & & The Netherlands \\
             & & \\
e-mail       &:& swan-info-citg@tudelft.nl \\
home page    &:& \hl{http://www.swan.tudelft.nl}
\end{tabular}
\end{table}

\vfill

\noindent
Copyright (c) 2006-2010 Delft University of Technology.
\\[2ex]
\noindent
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is available at
\hl{http://www.gnu.org/licenses/fdl.html\#TOC1}.

\clearpage
\pagestyle{myheadings}
\newcommand{\chap}[1] % Re-define the chapter command
       {
        \chapter{#1}
        \markboth{\hfill Chapter \thechapter \hfill}{\hfill {#1} \hfill}
       }

\tableofcontents

\chap{Introduction} \label{ch:intro}
\pagenumbering{arabic}

This document describes the programming rules for developing shallow water wave model SWAN.
It is essential for all programmers to strictly observe the rules set out in this document.
The programming rules should be suitable to support the programmer to make reliable, stable,
readable and structured source code.
It is furthermore recommended that the adjacent programs also comply with these rules, as this
results in a considerable simplification of maintenance, management and error tracking in particular.
\\[2ex]
\noindent
Chapter~\ref{ch:fortstd} discusses several general FORTRAN 90 standards, while programming of FORTRAN
control statements is dealt with in Chapter~\ref{ch:contr}.
Use of modules is outlined in Chapter~\ref{ch:modul}. The layouts of subroutines and modules are
the subject of Chapter~\ref{ch:layout}, and Chapter~\ref{ch:io} discusses input and output. Instructions
concerning errors are covered in Chapter~\ref{ch:err}. The pseudo code mentioned in Chapter~\ref{ch:layout},
is further discussed in Chapter~\ref{ch:pseudo}. Chapter~\ref{ch:optim} gives some advices on the improvement
of the code, while Chapter~\ref{ch:machdep} briefly considers machine
dependency. Chapter~\ref{ch:excep} describes exceptions to the FORTRAN 90 standards which goes against
programming ethics, but is nevertheless acceptable in certain prescribed cases because it strongly improves
user-friendliness. Chapter~\ref{ch:name} mentions several agreements on defining names for SWAN
subroutines and modules. Chapter~\ref{ch:examp} provides examples of a subroutine layout and module layout,
written according to the above-mentioned standards.
\\[2ex]
\noindent
This document has no final status, but will be developed and modified as experience and insight
are being gained. Please refer to the Log sheet for a summary of this document's modifications.
\\[2ex]
\noindent
The document uses different fonts for plain text and FORTRAN text.
The latter is in a sanserif {\tt typewriter} font.

\chap{FORTRAN 90 standards} \label{ch:fortstd}

When programming in any program language it is important to avoid obsolete, undesired and unnecssarily
complicated constructions, to have well documented codes and codes with a well-defined layout to support
easy understanding and desk checking. By satisfying the proposed rules as outlined below, the code
will be easier to transfer to other programmers. Rules will help the programmer to develop and maintain
the source code.
\\[2ex]
\noindent
The following rules should be consider for developing and extending the SWAN source code.
\begin{itemize}
  \item Code needs to be written in accordance with ANSI FORTRAN 90 standards.
        Good texts on programming in FORTRAN 90 are \cite{Cha98} and \cite{Mor93S}.
  \item Modular programming is strongly recommended.
  \item The program code is subdivided into program units $-$ or segments $-$ of a maximum of 500 source statements.
  \item Only one statement per line is allowed.
  \item The first line of every program unit is a {\tt PROGRAM}, {\tt SUBROUTINE}, {\tt FUNCTION} or {\tt MODULE}.
        The {\tt PROGRAM} statement is obligatory for a main program, and is followed by the comments as described
        in Chapter~\ref{ch:layout}.
  \item Every new program unit needs to be written in free format. Fixed format in the existing program units
        is acceptable for the time being. Note that an include file in free format cannot be included in a
        fixed form subroutine.
  \item New program units are given the '.f90' file extension and existing program units retain the '.f' extension
        (Linux/Unix) or the '.for' extension (Windows/DOS).
  \item An exclamation mark (!) is used in the $1^{st}$ column to indicate a comment line.
  \item It is preferably to use columns 1 to 5 for labels and columns 7 to 72 for statements (cf. FORTRAN 77).
  \item Every line contains a maximum of 80 characters. Insert an ampersand (\&) as a follow-on mark in the
        $73^{rd}$ column, and on the following line in the $6^{th}$ column.
  \item Parameter transfer between subroutines takes place preferably via a parameter list and otherwise
        via modules. Common blocks are not acceptable.
  \item All variables in a program unit need to be declared explicitly and be given the {\tt INTENT} attribute
        $-$ with the exception of pointers. The first declaration always needs to be the mandatory statement
        {\tt IMPLICIT NONE}. The implicit FORTRAN standard is still used for the purpose of clarity, i.e. integer
        names start with \textit{i} up to and including \textit{n}, complex variables with \textit{c} or \textit{z},
        and all remaining letters are reserved for reals.
  \item Each variable must be declared in a separate statement.
  \item Always use the sign {\tt ::} in the declaration list.
  \item Use the $*$ option as little as possible for array declaration, and define the actual length by means
        of parameters wherever possible. This enables good functioning of array bound checkers.
  \item Variable names have to be distinguishable in the first few characters.
  \item The meanings of names only apply within a program. They need to be as long as possible and have a logical structure,
        i.e. they should indicate their functions, preferably in English.
  \item Variables need to be given in alphabetical order.
  \item Use the type declaration instead of the dimension statement to declare local variables:
        \\[2ex]
        \noindent
        {\tt INTEGER IARRAY (100)}
        \\[2ex]
        \noindent
        instead of
        \\[2ex]
        \noindent
        {\tt DIMENSION IARRAY (100)}.
        \\[2ex]
        \noindent
        Never use real expressions in array dimensions.
  \item Mixed-mode expressions (single-precision/double-precision) are not used.
  \item Always initialize pointers with the {\tt NULLIFY} instruction.
  \item Use as many \textit{allocatable} arrays as possible, and as little \textit{automatic} arrays or fixed-length arrays as
        possible. The reason is that automatic arrays are placed on the stack, which has a limited size,
        so that large arrays can easily cause \textit{stack overflow}. By contrast, allocatable arrays are always
        stored in the heap memory.
  \item If allocatable arrays are no longer used, they must always be deallocated at the end of the subroutine.
  \item For validity checks, preference is given to the {\tt STAT=} attribute for the purpose of array allocation/deallocation.
  \item Use {\tt POINTER} and {\tt TARGET} for very large data sets or linked lists for which the length
        is not known beforehand.
  \item Always end a do loop with {\tt END DO} instead of {\tt CONTINUE}. In the case of nested do loops, every do
        loop must end with its own {\tt END DO} statement.
  \item Use labels to identify the structure of do loops since, this will improve the readability of the
        code.
  \item A combination of upper case and lower case may improve readability, but is not a standard for
        fixed-format (cf. FORTRAN 77). In general small letters are recommended.
  \item Make ample use of spaces, comment blocks and extra space between lines.
  \item Use multi-dimensional arrays where they match the logical structure, unless this leads to a
        considerable increase in memory required. Do not use special auxiliary variables for the purpose
        of efficient programming. The compilers achieve this anyway, and the special variables do not
        improve readability.
  \item Use the {\tt SAVE} attribute (not the {\tt SAVE} statement!) when the value of a variable
        must be retained in the next call of a subroutine.
  \item Use the parameter statement to define values for constants. This should be done for the logical
        unit numbers, array dimensions and physical and numerical constants. The numbers are defined
        on just one place in the program (e.g. module), so that changing the value can be done once.
        Some constants should not be parameterised, such as $\pi$ which can be calculated with an
        intrinsic function: {\tt PI = 4.*ATAN(1.)}.
  \item Statement labels need to meet the following conditions:
        \begin{itemize}
          \item They are used exclusively for {\tt FORMAT} statements.
          \item They are used in ascending order.
        \end{itemize}
  \item Character strings need to meet the following conditions:
        \begin{itemize}
          \item A string which enters a subroutine via the argument list, must be dimensioned
                as a variable in that subroutine: {\tt CHARACTER (LEN=*)}.
          \item The string length may not be transferred via the argument list. The length is
                determined via intrinsic function {\tt LEN}.
          \item Strings should not be used as operands in relational operators, such as
                {\tt .LT.}, {\tt .GT.}, {\tt .EQ.}, {\tt .NE.}, {\tt .LE.}, {\tt .GE.}. Use
                FORTRAN functions {\tt LGE}, {\tt LGT}, {\tt LLE}, {\tt LLT} instead.
          \item {\tt ICHAR} and {\tt CHAR} must not be used in a way that makes the code dependent on the
                underlying character set (ASCII, EBCDIC). Use the {\tt IACHAR} and {\tt ACHAR} statements to
                obtain an ASCII number of a specific character $-$ or to do the reverse.
        \end{itemize}
  \item Do not use free format output, i.e. $*$, but always use {\tt FORMAT} statements. This
        facilitates the comparison of the output obtained on various computers. The use of a format
        in the {\tt WRITE} statement itself is not recommended, since it does not improve the
        readableness.
  \item Use arrays as units in expressions to improve readability. This means that the arrays can be treated
        as scalar quantities, and can therefore be subject to practically all scalar operations and functions.
  \item Avoid data-dependency in array expressions.
  \item Initialize every variable in a subroutine and never assume the compiler sets any value at 0. Avoid saving
        a local variable value as much as possible. If this value does need to be saved, then a {\tt SAVE} attribute
        must be used.
  \item Do not use the following, obsolete, standard FORTRAN 77 statements:
        \begin{itemize}
          \item Statement functions, i.e. a function in one line within a different routine.
          \item Assigned goto.
          \item Named common en blank common.
          \item Arithmetic if ({\tt IF ... 100, 200, 300}).
          \item {\tt EQUIVALENCE}
          \item {\tt ENTRY}
          \item {\tt ERR=} and {\tt END=} in read instructions; use {\tt IOSTAT} specifier instead.
          \item {\tt PAUSE}
          \item More than one entry or output per module ({\tt ENTRY}, alternate {\tt RETURN}).
          \item Jump to {\tt ENDIF} from outside {\tt IF} block.
          \item Non-integer index in a do loop.
          \item The H edit descriptor.
        \end{itemize}
  \item Always use the generic name for intrinsic functions, so {\tt ABS} instead of {\tt CABS} or {\tt DABS}.
  \item Use the following operators in subroutines to be generated: {\tt >}, {\tt >=}, {\tt <}, {\tt =<}, {\tt ==} and
        {\tt /=}. Using the former style, such as {\tt .GT.} and {\tt .NE.}, is acceptable in existing subroutines.
  \item Do not use a {\tt STOP} except in the following cases:
        \begin{itemize}
          \item an error subroutine after printing of a fatal error,
          \item in an explicit lockup routine
        \end{itemize}
  \item Use the {\tt SELECT CASE} construct in the case of more than two mutually exclusive choices.
  \item Do not use {\tt WHERE} statements, as these generally have a negative effect on performance.
  \item Do not use BLAS routines.
  \item Do not use a {\tt GOTO} statement except for error handling. Jump to a {\tt CONTINUE} statement with a
        numerical label (usually 9999), after which the error can be dealt with.
  \item Develop the code such that it may improve the performance. This means that clean do loops
        should be used and, that {\tt IF THEN ELSE} constructions should be placed outside the do loops,
        if appropriate. See also Chapter~\ref{ch:optim} for more details on how to optimize the code.
  \item Do not write intermediate results to background memory unless there is a very good reason to
        do so. I/O is very expensive and must therefore be avoided wherever possible. It is often much
        more favorable to save the intermediate results in an array or, if not enough memory is available,
        to recompute them.
  \item In the case of multi-dimensional arrays applied in nested do loops, it is preferred to use the
        inner loop for the first index. On vector computers and machines containing a cache memory, this
        approach results in a considerably higher efficiency.
\end{itemize}

\chap{Control statements} \label{ch:contr}

In principle, a net program contains three control structure:
\begin{itemize}
  \item sequence,
  \item selection and
  \item iteration.
\end{itemize}
These program statements for FORTRAN are discussed below. Other constructions and FORTRAN
control statements should not be applied.
\\[2ex]
\noindent
\begin{itemize}
  \item Sequence. \\
        This is a series of statements and/or references to a process elsewhere (via {\tt CALL}).
        Exit a subroutine only via {\tt END}.
  \item Selection. \\
        There are two constructions allowed:
        \begin{itemize}
           \item IF - THEN - ELSE
           \item SELECT CASE
        \end{itemize}
        The first construction enables a choice to be made between two options and is programmed as follows:
        \begin{verbatim}
          IF (condition) THEN
             statements
          ELSE
             andere statements
          ENDIF
        \end{verbatim}
        The second construction is programmed as follows:
        \begin{verbatim}
          SELECT CASE (variable)
             CASE (value1)
                 statements
             CASE (value2)
                 statements
             ...
             CASE default
                 other statements
          END SELECT
        \end{verbatim}
        An alternative for the latter construction is the construction {\tt IF - THEN - ELSEIF - ELSE}.
        A major disadvantage of this construction is that all alternatives need to be tested, even if it takes
        until the end of the list to find that an option in fact applies.
  \item Iteration. \\
        There are various iteration options, but only the following three are allowed:
        \begin{itemize}
           \item DO - ENDDO
           \item DO WHILE
           \item REPEAT UNTIL
        \end{itemize}
        The first construction is a counter-controlled loop:
        \begin{verbatim}
           DO i = istart, iend, istep
              statements
           ENDDO
        \end{verbatim}
        If necessary, use the {\tt CYCLE} and {\tt EXIT} statements to immediately start the next iteration step of the
        loop or to exit the loop, respectively.
        \\[2ex]
        \noindent
        Although, FORTRAN 90 does recognize the {\tt DO WHILE} statement, it is recommended to simulate this
        construction by using the {\tt EXIT} statement:
        \begin{verbatim}
           DO
              IF (.NOT.condition) EXIT
              statements
           ENDDO
        \end{verbatim}
        instead of
        \begin{verbatim}
           DO WHILE (condition)
              statements
           ENDDO
        \end{verbatim}
        The third construction is programmed as follows:
        \begin{verbatim}
           DO
              statements
              IF (condition) EXIT
           ENDDO
        \end{verbatim}
\end{itemize}

\chap{Use of modules} \label{ch:modul}

The idea of modules is data hiding and locality. Place groups of related subroutines and data
together in one module. Common parts of the software architectures of the system are candidate
to be placed in modules.
\\[2ex]
\noindent
Due to the availability of modules, common blocks are prohibited.
\\[2ex]
\noindent
Explicit interfaces should be use. The interfaces are automatically known in the calling routines
by means of the {\tt USE} statement. Two ways are possible:
\begin{itemize}
  \item Place the whole subroutines in the module.\\
        The drawback is, however, that a small change in a module procedure, even it is declared
        private and the interfaces are not changed, can cause a cascade of compilations in all
        the places where the module is used.
  \item Place only the interfaces in the module.\\
        The drawback is that the interfaces appear twice: in the subroutine and in the module.
\end{itemize}
Both choices are allowed.
\\[2ex]
\noindent
Make the interfaces of the subroutines explicit. Place several modules where the interfaces and subroutines
are programmed in the same file. Redefinition of functions is only allowed when a naming conflict
occures, otherwise redefinition of functions is prohibited.
\\[2ex]
\noindent
All entities in a module must be declared private by default, and thereafter the entities are declared
public which have to be known outside the module. Modules may not contain data that is shared by
different subroutines of a program. Modules may contain private data.
\\[2ex]
\noindent

\chap{Program layout} \label{ch:layout}

The following general rules apply to the layout:
\begin{itemize}
  \item In the case of nesting, indent by three positions.
  \item Separate the sub program units by brief comments lines.
  \item Insert a extra space before and after every comment block.
  \item Never use {\em tabs}, as this causes problems with transport to other machines.
\end{itemize}
The standard layout of a program or subroutine is described below.
\begin{enumerate}
  \item Program unit statement ({\tt PROGRAM}, {\tt SUBROUTINE}, {\tt FUNCTION}, {\tt MODULE}).
  \item Comment block consisting of:
        \begin{itemize}
          \item Programmer's name.
          \item Version number followed by the date and machine on which it was developed
          \item Version numbers of the modifications including dates, followed by a brief description of the
                modification and the reason for modifying.
          \item Any applicable copyright, preferably GNU Public License (see \hl{http://www.gnu.org}).
          \item Description of the subroutine function, if necessary with reference to a detailed design.
        \end{itemize}
        The version number consists of several digits separated by a decimal point, and has a start value of
        1.0. Major modifications result in an increase by a value 1 of digit 1, and in the decimal being set at 0.
        The modified digits are filled in on the next line to retain the previous information, and the
        modification is briefly described in brackets. Minor modifications result in the decimal being increased
        by a value 1 and, if required, a brief description of the modification.
        \\[2ex]
        \noindent
        Routines which are clearly sensitive to machine accuracy contain a warning in the comments.
  \item Declaration of input and output variables, followed by a comment block with a description of these
        variables marked with \textit{i} (input) and/or \textit{o} (output).
        Use the lexicographic order, and always use the {\tt INTENT} attribute.
  \item Local variables:
        \begin{itemize}
            \item Declaration of variables.
            \item Any {\tt SAVE} attributes, parameter and data statements.
            \item A comment block with a description of all local variables. Use the lexicographical order.
        \end{itemize}
  \item Comment block consisting of:
        \begin{itemize}
          \item I/O description including unit numbers and files used.
          \item Description of all subroutines used.
          \item Description of all subroutines which call the current subroutine.
          \item Error messages.
          \item Description of the module as a pseudo code (see Chapter~\ref{ch:pseudo}).
        \end{itemize}
  \item Program text.\\
        Format statements are given at the end of the program unit.
\end{enumerate}
A template format of a subroutine is given in Chapter~\ref{ch:examp}. No layout must be used for SWAN other than the layout
of that example.

\chap{Input en output} \label{ch:io}

\begin{itemize}
   \item Do not use the {\tt PRINT} statement, but only the i/o statement keywords {\tt READ} and {\tt WRITE}. Never use
         $*$ as a device number because the device linked to $*$ is machine-dependent.
   \item File unit numbers should be provided by a generic function or subroutine.
   \item Use variables for logical unit numbers in {\tt READ} and {\tt WRITE} statements.
   \item Logical unit numbers smaller than 11 are prohibited.
   \item Always use {\tt IOSTAT=} instead of {\tt ERR=} or {\tt END=} for testing on i/o status.
   \item Only use a blank for carriage control.
   \item Create user-friendly error messages including the name of the module where the error occurred.
   \item Close files which are no longer used.
   \item Open statements are machine-dependent (see Chapter~\ref{ch:machdep}).
   \item The input should not differentiate between upper case and lower case.
   \item Input of numerical data should always be free format.
\end{itemize}

\chap{Error messages} \label{ch:err}

The standard option selected for errors is the \textit{hard} option (imperative). This means that a message
appears when an error occurs and, if necessary, the activity is aborted. The \textit{soft} option (non-imperative)
is applied only in the case of a numerical method error, for example due to a lack of
convergence. The activity may be continued, while an error number is added to the parameter
list. The imperative option is set as default, so users need to define explicitly if they
prefer the non-imperative option, by means of a parameter in the parameter list.
\\[2ex]
\noindent
Differentiate between errors and warnings.
\\[2ex]
\noindent
Always stop if too many, for example 10, errors
occur and print a maximum of 10 warnings. The error subroutine entails a {\tt STOP} only if the
number of errors is exceedingly high. A {\tt STOP} needs to be built into the calling subroutine
after fatal errors. In the case of input errors, continue until all errors have been given.

\chap{Pseudo code} \label{ch:pseudo}

\section{Using the pseudo code}

It is recommended that all programmers use the same conventions for the pseudo code. For
a mathematical description of the algorithm, the algorithm needs to be written exactly as
it would appear in an article. Use superscripts and subscripts for upper and lower indices
respectively.
\\[2ex]
\noindent
Provide clear translations for unavailable symbols, for example \textit{sqrt} (square root) or \textit{sum} (sum).
\\[2ex]
\noindent
The structures used are those resembling a structural diagram, except that indentations are
used instead of lines. An alternative is Jackson Structured Programming (JSP), but its
readability is slightly less than that of a structural diagram.\\
The three control structures result in:
\begin{itemize}
  \item sequence\\
        Statements are described one below the other.
  \item selection
        \begin{itemize}
          \item IF - THEN - ELSE:
              \begin{verbatim}
                 if ... then
                    statements
                 else
                    statements
              \end{verbatim}
          \item SELECT - CASE:
              \begin{verbatim}
                 select ...
                   case ..
                     statements
                   case ..
                     statements
                   ...
                   else
                     statements
              \end{verbatim}
        \end{itemize}
  \item iteration\\
        The three allowed structures are written as follows:
        \begin{itemize}
           \item DO ENDDO
                  \begin{verbatim}
                     for i = i1 (i2) i3
                        statements
                  \end{verbatim}
           \item DO WHILE
                  \begin{verbatim}
                     while ...
                        statements
                  \end{verbatim}
           \item REPEAT UNTIL
                  \begin{verbatim}
                     repeat until ...
                        statements
                  \end{verbatim}
        \end{itemize}
\end{itemize}

\section{Input and output}

Input and output can be given in descriptive text, which needs to include the source file or
source machine of the input and output. Considering the fact that many computers have some standard
input, such as batch data or keyboard/terminal, and some standard output, such as a screen or printer,
the abbreviations STDIN and STDOUT can be used as standard files. All other files need to be named by
means of an {\tt OPEN}, after which they need to be closed again.

\section{Further operations}

In general, it is useful to give an outline in descriptive text and to avoid irrelevant details.
Use as little programming-language dependent phrases as possible. If more details need to be given,
a FORTRAN/PASCAL type code can be used, for example formulas including +, $-$,  *, /, and (). For
assigning, := is preferred. Conditions may include =, $>$, $<$, etc., but not as logical expressions.
\\[2ex]
\noindent
In pseudo code no type distinction is made between integers and reals. Numbers are considered
real with infinite accuracy. If necessary, although rarely,
PASCAL operators DIV (integer division) and MOD (remainder) can be used.
\\[2ex]
\noindent
Notes:
\begin{itemize}
  \item The purpose of the pseudo code is to give a clear description of the algorithm. It is not
        the purpose to describe each statement in the pseudo code. However, the pseudo code must be
        such that an arbitrary programmer may code the subroutine immediately from the pseudo code.
  \item If the formulas or the algorithms are so complicated that there is no point in including them
        into the source codes, it is sufficient to refer to a document giving the full details.
        This document must be mentioned next to the source code.
\end{itemize}

\chap{Some advices on the improvement of performance} \label{ch:optim}

Below we shall give some advices of how to improve the performance of a code.
\begin{itemize}
   \item Use only clean loops without {\tt IF}, {\tt GOTO} or {\tt CALL} statements. For example:
         \begin{verbatim}
            DO i = 1, n
               IF ( var > 0 ) THEN
                  a(i) = 0.
               ELSE
                  a(i) = b(i)
               ENDIF
            ENDDO
         \end{verbatim}
         should be replaced by
         \begin{verbatim}
            IF ( var > 0 ) THEN
               a(:) = 0.
            ELSE
               a(:) = b(:)
            ENDIF
         \end{verbatim}
   \item Make sure that the inner loop is the longest one of a series of nested do loops.
   \item Use the inner loop for the first index of multi-dimensional arrays in case of nested
         loops. This may increase the efficiency, provided the inner loop is long enough.
   \item Avoid indirect addressing, if possible.
   \item Avoid division in a do loop.
   \item Avoid (seemingly) recursions in a loop.
\end{itemize}

\chap{Machine dependency} \label{ch:machdep}

Machine dependency can be found in various cases, in particular:
\begin{itemize}
  \item Precision used for calculating.
  \item Open statements.
  \item Machine-dependent constants.
  \item Plot instructions.
\end{itemize}
These cases are discussed below.
\begin{itemize}
  \item There are computers which calculate in 64 bits, for example several super computers such as CRAY.
        This means that large-scale numerical applications need to be calculated in double-precision. The
        following rules need to be observed for easy distillation of a single-precision version from such
        a double-precision version:
        \begin{itemize}
          \item Declare explicitly with {\tt DOUBLE PRECISION} or {\tt COMPLEX * 16}, repeat the declaration with {\tt REAL}
                and {\tt COMPLEX}, but include the letter combination \textit{ce} into the relevant lines in columns 1 and 2. Always
                write {\tt DOUBLE PRECISION} with one space and always write {\tt COMPLEX * 16} with one space on either side
                of the $*$. Always write these statements in lower case.
          \item Always use generic names for intrinsic functions.
        \end{itemize}
        These rules allow the simple conversion of a double-precision into a single-precision version and vice versa.
  \item Unfortunately, open statements are machine-dependent. The filename presents the biggest problem.
        According to the official standard the filename can be incorporated into the open statement, but an
        IBM mainframe rejects this. It is therefore necessary to include as many open statements as possible
        in one machine-dependent subroutine. Additionally, different computers can then accept different
        filenames.
  \item Certain machine-dependent constants, such as machine accuracy and largest real number,
        are used in many programs. It is recommended to initialize these constants in a general
        machine-dependent subroutine and to include them in a module.
  \item Plot instructions are not only machine-dependent, but also device-dependent and package-dependent.
        Using real plot calls in programming should be avoided. This can be done by creating a separate
        plot routine which simulates plot calls $-$ at any level. This plot routine can contain the
        machine-dependent calls or, if necessary, can generate a local neutral file. It is recommended
        to use as few separate machine-dependent plot routines as possible.
\end{itemize}

\chap{Exceptions} \label{ch:excep}

There is a situation where an explicit deviation from the FORTRAN standard is acceptable, namely array
transfer to underlying subroutines. On the one hand, it is accepted that the dimension number and
size in a current array are different to the number and size in an associated dummy argument array
declarator, while on the other hand it is accepted that arrays are transferred by using the start
address. In both situations explicit use is therefore made of the FORTRAN characteristic that array
transfer means no more than start address transfer.
\\[2ex]
\noindent
It goes without saying that this option goes against programming ethics and should therefore be
avoided wherever possible, although its use is inevitable in larger packages. Several reasons are:
\begin{itemize}
  \item In certain subroutines, the option preferred from a structural point of view is to use an array as
        an $n$-dimensional array (e.g. for the matrix structure), whereas in other subroutines an $m$-dimensional
        array is preferred (e.g. for the linear solver). If the same dimension were used in both subroutines,
        the address calculations would need to be carried out time and again. This has a negative effect on
        efficiency and definitely on readability.
  \item Another reason for array transfer by using start addresses, is that it avoids the number of parameters
        in a routine at top level and therefore avoids errors. From a structural point of view, however, it is
        preferred to work with several arrays in the underlying subroutines.
\end{itemize}
It is clear that the above approach is not without its risks and is therefore not allowed, except in
the top layer of subroutines the user needs to handle. All underlying subroutines must be neat and tidy.
In addition, if these options are used, the array bounds need to be checked carefully, because neither
checkers nor debuggers are then able to carry out the checks.

\chap{Names for SWAN program units} \label{ch:name}

SWAN subroutines at top level can be given any name, because the user is familiar with these routines.
The names therefore need to be mnemonic. It is recommended to opt for specific combinations for
underlying subroutines, however, so that users with their own programming do not run into name
conflicts. The suggestion is to start all SWAN routines with the letter combination \textit{sw}.
\\[2ex]
\noindent
Unambiguous names are also necessary for the modules. For SWAN, the combination \textit{swmod} could for example
be followed by a 3-digit symbol.
\\[2ex]
\noindent
In any case, it is essential that an ASCII file with applied subroutine
names and modules is kept up-to-date, including a brief description of the functionalities.

\chap{Examples} \label{ch:examp}

Below a template of a SWAN subroutine layout of \underline{fixed format} is given that complies with the programming rules set out in this document.
\\[2ex]
\begin{verbatim}
!****************************************************************
!
      SUBROUTINE SWBODY ()
!
!****************************************************************
!
      USE OCPCOMM4
!
      IMPLICIT NONE
!
!
!   --|-----------------------------------------------------------|--
!     | Delft University of Technology                            |
!     | Faculty of Civil Engineering                              |
!     | Environmental Fluid Mechanics Section                     |
!     | P.O. Box 5048, 2600 GA  Delft, The Netherlands            |
!     |                                                           |
!     | Programmers: The SWAN team                                |
!   --|-----------------------------------------------------------|--
!
!
!     SWAN (Simulating WAves Nearshore); a third generation wave model
!     Copyright (C) 2002  Delft University of Technology
!
!     This program is free software; you can redistribute it and/or
!     modify it under the terms of the GNU General Public License as
!     published by the Free Software Foundation; either version 2 of
!     the License, or (at your option) any later version.
!
!     This program is distributed in the hope that it will be useful,
!     but WITHOUT ANY WARRANTY; without even the implied warranty of
!     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
!     GNU General Public License for more details.
!
!     A copy of the GNU General Public License is available at
!     http://www.gnu.org/copyleft/gpl.html#SEC3
!     or by writing to the Free Software Foundation, Inc.,
!     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
!
!
!  0. Authors
!
!     40.23: Marcel Zijlema
!
!  1. Updates
!
!     40.23, Aug. 02: New subroutine
!
!  2. Purpose
!
!     Description of the purpose of this subroutine
!
!  3. Method
!
!     Description of the method
!
!  4. Argument variables
!
!     VARIABLE    meaning
!
      INTEGER, INTENT(IN) :: VARIABLE
      REAL
      CHARACTER (LEN=n)
      LOGICAL
!
!  5. Parameter variables
!
!     ---
!
!  6. Local variables
!
!     I     :     counter
!     J     :     counter
!
      INTEGER :: I, J
!
!  8. Subroutines used
!
!     ---
!
!  9. Subroutines calling
!
!     ---
!
! 10. Error messages
!
!     ---
!
! 11. Remarks
!
!     ---
!
! 12. Structure
!
!     Description of the pseudo code
!
! 13. Source text
!
      SAVE IENT
      DATA IENT/0/
      IF (LTRACE) CALL STRACE (IENT,'SWBODY')

      ...
      RETURN
      END
\end{verbatim}

\newpage
\noindent
Below a template of a SWAN subroutine layout of \underline{free format} is given that complies with the programming rules set out in this document.
\\[2ex]
\begin{verbatim}
subroutine SwanRoutineBody ()
!
!   --|-----------------------------------------------------------|--
!     | Delft University of Technology                            |
!     | Faculty of Civil Engineering and Geosciences              |
!     | Environmental Fluid Mechanics Section                     |
!     | P.O. Box 5048, 2600 GA  Delft, The Netherlands            |
!     |                                                           |
!     | Programmer: M. Zijlema                                    |
!   --|-----------------------------------------------------------|--
!
!
!     SWAN (Simulating WAves Nearshore); a third generation wave model
!     Copyright (C) 2007  Delft University of Technology
!
!     This program is free software; you can redistribute it and/or
!     modify it under the terms of the GNU General Public License as
!     published by the Free Software Foundation; either version 2 of
!     the License, or (at your option) any later version.
!
!     This program is distributed in the hope that it will be useful,
!     but WITHOUT ANY WARRANTY; without even the implied warranty of
!     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
!     GNU General Public License for more details.
!
!     A copy of the GNU General Public License is available at
!     http://www.gnu.org/copyleft/gpl.html#SEC3
!     or by writing to the Free Software Foundation, Inc.,
!     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
!
!
!   Authors
!
!   40.80: Marcel Zijlema
!
!   Updates
!
!   40.80, July 2007: New subroutine
!
!   Purpose
!
!   Description of the purpose of this subroutine
!
!   Method
!
!   Description of the method
!
!   Modules used
!
    use ocpcomm4
!
    implicit none
!
!   Argument variables
!
    integer, intent(in) :: variable ! description variable
    real
    character(n)
    logical
    double precision
!
!   Parameter variables
!
!   ---
!
!   Local variables
!
    integer       :: i        ! loop counter
    integer, save :: ient = 0 ! number of entries in this subroutine
!
!   Structure
!
!   Description of the pseudo code
!
!   Source text
!
    if (ltrace) call strace (ient,'SwanRoutineBody')

    ...

end subroutine SwanRoutineBody
\end{verbatim}

\newpage
\noindent
Below a template of a SWAN module layout of \underline{fixed format} is given that complies with the programming rules set out in this document.
\\[2ex]
\begin{verbatim}
      MODULE MODBODY
!
!
!   --|-----------------------------------------------------------|--
!     | Delft University of Technology                            |
!     | Faculty of Civil Engineering                              |
!     | Environmental Fluid Mechanics Section                     |
!     | P.O. Box 5048, 2600 GA  Delft, The Netherlands            |
!     |                                                           |
!     | Programmers: The SWAN team                                |
!   --|-----------------------------------------------------------|--
!
!
!     SWAN (Simulating WAves Nearshore); a third generation wave model
!     Copyright (C) 2005  Delft University of Technology
!
!     This program is free software; you can redistribute it and/or
!     modify it under the terms of the GNU General Public License as
!     published by the Free Software Foundation; either version 2 of
!     the License, or (at your option) any later version.
!
!     This program is distributed in the hope that it will be useful,
!     but WITHOUT ANY WARRANTY; without even the implied warranty of
!     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
!     GNU General Public License for more details.
!
!     A copy of the GNU General Public License is available at
!     http://www.gnu.org/copyleft/gpl.html#SEC3
!     or by writing to the Free Software Foundation, Inc.,
!     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
!
!
!  0. Authors
!
!     40.41: Marcel Zijlema
!
!  1. Updates
!
!     40.41, Apr. 05: New Module
!
!  2. Purpose
!
!     ---
!
!  3. Method
!
!     MODULE construct
!
!  4. Modules used
!
!     ---
!
      IMPLICIT NONE
!
!  5. Argument variables
!
!     ---
!
!  6. Parameter variables
!
!     ---
!
!  7. Local variables
!
!     ---
!
!  8. Subroutines and functions used
!
!     ---
!
!  9. Subroutines and functions calling
!
!     ---
!
! 10. Error messages
!
!     ---
!
! 11. Remarks
!
!     ---
!
! 12. Structure
!
!     ---
!
! 13. Source text
!
      END MODULE MODBODY
\end{verbatim}

\newpage
\noindent
Below a template of a SWAN module layout of \underline{free format} is given that complies with the programming rules set out in this document.
\\[2ex]
\begin{verbatim}
module SwanModuleBody
!
!   --|-----------------------------------------------------------|--
!     | Delft University of Technology                            |
!     | Faculty of Civil Engineering and Geosciences              |
!     | Environmental Fluid Mechanics Section                     |
!     | P.O. Box 5048, 2600 GA  Delft, The Netherlands            |
!     |                                                           |
!     | Programmer: M. Zijlema                                    |
!   --|-----------------------------------------------------------|--
!
!
!     SWAN (Simulating WAves Nearshore); a third generation wave model
!     Copyright (C) 2007  Delft University of Technology
!
!     This program is free software; you can redistribute it and/or
!     modify it under the terms of the GNU General Public License as
!     published by the Free Software Foundation; either version 2 of
!     the License, or (at your option) any later version.
!
!     This program is distributed in the hope that it will be useful,
!     but WITHOUT ANY WARRANTY; without even the implied warranty of
!     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
!     GNU General Public License for more details.
!
!     A copy of the GNU General Public License is available at
!     http://www.gnu.org/copyleft/gpl.html#SEC3
!     or by writing to the Free Software Foundation, Inc.,
!     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
!
!
!   Authors
!
!   40.80: Marcel Zijlema
!
!   Updates
!
!   40.80, July 2007: New Module
!
!   Purpose
!
!   Description of the purpose of this module
!
!   Method
!
!   MODULE construct
!
!   Modules used
!
!   ---
!
    implicit none
!
!   Module parameters
!
!   ---
!
!   Module variables
!
!   ---
!
!   Source text
!
end module SwanModuleBody
\end{verbatim}

\newpage
\markboth{}{}
\begin{thebibliography}{10}
\addcontentsline{toc}{chapter}{Bibliography}

\bibitem{Cha98}
Chapman, S.J. (1998). {\it Fortran 90/95 for scientists and engineers}, WCB McGraw-Hill, Boston, USA.

\bibitem{Mor93S}
Morgan, J.S. and J.L. Schonfelder (1993). {\it Programming in Fortran 90}, Alfred Waller Ltd.,
Henley-on-Thames.

\end{thebibliography}

\backmatter{}

\chap{Log sheet}

\begin{table}[htb]
\begin{tabular}{l l l}
\hline
  Document & Date             & Modification of previous version \\
  version  &                  &                                  \\
\hline
   1.0     & April 28, 2005   & Initial document                 \\
           &                  &                                  \\
   1.1     & May 19, 2005     & Minor modifications in response  \\
           &                  & to comments by RWS $-$ RIKZ      \\
           &                  &                                  \\
   1.2     & January 10, 2006 & Translation into English         \\
           &                  &                                  \\
   1.3     & March 22, 2006   & Some minor modifications and     \\
           &                  & extensions                       \\
\hline
\end{tabular}
\end{table}

\end{document}
