source: trunk/DOC/TexFiles/Chapters/Annex_D.tex @ 994

% ================================================================
% Appendix D Ñ Coding Rules
% ================================================================
\chapter{Coding Rules}
\label{Apdx_D}
\minitoc


A "model life" is more than ten years. Its software, composed by a few 
hundred modules, is used by many people who are scientists or students and 
do not necessary know very well all computer aspects. Moreover, a well 
thought-out programme is easy to read and understand, less difficult to 
modify, produces fewer bugs and is easier to maintain. Therefore, it is 
essential that the model development follows some rules :

- well planned and designed

- well written

- well documented (both on- and off-line)

- maintainable

- easily portable

- flexible.

To satisfy part of these aims, \NEMO is written with a coding standard which 
is close to the ECMWF rules, named DOCTOR \citep{Gibson_TR86}. These rules present some advantages like :

- to provide a well presented program

- to use rules for variable names which allow recognition of their type 
(integer, real, parameter, local or shared variables, etc. ) so that debugging is 
facilitated.

% ================================================================
% The program structure
% ================================================================
\section{The program structure}
\label{Apdx_D_structure}

Each program begins with a set of headline comments containing :

- the program title

- the purpose of the routine

- the method and algorithms used

- the detail of input and output interfaces

- the external routines and functions used (if exist)

- references (if exist)

- the author name (s), the date of creation and of updates.

- Each program is splitted into several well separated sections and 
sub-sections with a underlined title and specific labelled statements.

- A program has not more than 200 to 300 lines.

% ================================================================
% Coding conventions
% ================================================================
\section{Coding conventions}
\label{Apdx_D_coding}

- Use of the universal language \textsc{Fortran} 5 ANSI 77, with non 
standard extensions, NAMELIST and \textsc{Fortran} 90 (matrix resolution 
algorithm), and some well-identified particular statements or functions for 
weak and massive parallelism, and vectorization 

- A comment line begins with a uppercase character C at the first column. A 
space line must have a C. For the on-line documentation, comments are 
classified into three levels :

Overview, triggered by CCC in columns 1 to 3. Only the title and the purpose 
of the program are identified like that. This overview documentation can be 
extracted by the UNIX function : grep -e '\^{}CCC' *

External, triggered by CC in columns 1 to 2, and which correspond to 
headlines of each programme, extracted by : grep -e '\^{}CC' *

Internal which are all the comments, extracted by : grep -e '\^{}C' *

- Statements GO TO, EQUIVALENCE are forbidden.

- A section is numbered with labels which are in agreement with the 
paragraph label and increase from the begin to the end of routine. Labels of 
a hundred ( 200, 201.. 220..) are reserved to a unique section. The 
\textsc{Fortran} 90 extension syntax DO/ENDDO is used except for multitasked 
do-loop. In this case labels 1000, 2000, ... are used. The FORMAT statement 
are labelled with numbers in the range 9000 to 9999.

- A continuation line begins with the character {\$} in column 6.

- All statements begin in column 7 with the following gaps :

2 spaces toward the right in a DO loop.

4 spaces toward the right in IF, ELSEIF, ELSE and ENDIF statements, with 
only 2 spaces for ELSE and ELSEIF lines. All IF statement must be followed 
by a ELSE statement.

Some spaces in the continuation line for alignment.

- Use of different labels for each DO loop statement.

- STOP must be well documented with the name of the subroutine or a number.

% ================================================================
% Naming Conventions
% ================================================================
\section{Naming Conventions}
\label{Apdx_D_naming}

The purpose of the naming conventions is to use prefix letters to classify 
model variables. These conventions allow to know easily the variable type 
and to identify them rapidly:


%--------------------------------------------------TABLE--------------------------------------------------
\begin{table}[htbp]
\begin{center}
\begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
\hline  Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\  
\hline
public & 
\textbf{m n} \par \textit{but not } \par \textbf{nam}& 
\textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{sf}& 
\textbf{l} \par \textit{but not} \par \textbf{lp ld ll}& 
\textbf{c} \par \textit{but not} \par \textbf{cp cd cl } \par \textbf{com cim}& 
\textbf{d} \par \textit{but not} \par \textbf{dp dd dl}& 
\textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
\hline
dummy \par argument& 
\textbf{k} \par \textit{but not} \par \textbf{kf}& 
\textbf{p} \par \textit{but not}  \par \textbf{pp pf}& 
\textbf{ld}& 
\textbf{cd}& 
\textbf{dd}& 
\textbf{yd} \\
\hline
local \par variable& 
\textbf{i}& 
\textbf{z}& 
\textbf{ll}& 
\textbf{cl}& 
\textbf{cd}& 
\textbf{yl} \\
\hline
loop \par control& 
\textbf{j} \par \textit{but not } \par \textbf{jp}& 
& 
& 
& 
& 
 \\
\hline
parameter& 
\textbf{jp}& 
\textbf{pp}& 
\textbf{lp}& 
\textbf{cp}& 
\textbf{dp}& 
\textbf{yp} \\
\hline
statement \par function& 
\textbf{kf}& 
\textbf{sf} \par & 
& 
& 
& 
 \\
\hline
\end{tabular}
\label{tab1}
\end{center}
\end{table}
%--------------------------------------------------------------------------------------------------------------