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


A "model life" is more than ten years. Its software, composed of a few 
hundred modules, is used by many people who are scientists or students 
and do not necessarily know every aspect of computing very well. 
Moreover, a well thought-out program is easier 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 they exist)

- references (if they exist)

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

- Each program is split into several well separated sections and 
sub-sections with an 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} 90, and try to avoid obsolescent
features like statement functions, do not use GO TO and EQUIVALENCE statements.

- A continuation line begins with the character {\$} indented by three spaces 
compared to the previous line.

- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF 
statements.

- use call to ctl\_stop routine instead of just a STOP.

% ================================================================
% 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 the variable type to be easily known
and rapidly identified:

%--------------------------------------------------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  \par or  \par module variable& 
\textbf{m n} \par \textit{but not } \par \textbf{nn\_}& 
\textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& 
\textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}& 
\textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}& 
\textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}& 
\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

namelist&
\textbf{nn\_}& 
\textbf{rn\_}& 
\textbf{ln\_}& 
\textbf{cn\_}& 
\textbf{dn\_}& 
\\
\hline
CPP \par macro& 
\textbf{kf}& 
\textbf{sf} \par & 
& 
& 
& 
 \\
\hline
\end{tabular}
\label{tab1}
\end{center}
\end{table}
%--------------------------------------------------------------------------------------------------------------