source: NEMO/branches/2018/dev_r10164_HPC09_ESIWACE_PREP_MERGE/doc/latex/NEMO/subfiles/annex_D.tex @ 10368

Last change on this file since 10368 was 10368, checked in by smasson, 22 months ago

dev_r10164_HPC09_ESIWACE_PREP_MERGE: merge with trunk@10365, see #2133

File size: 6.3 KB
Line 
1\documentclass[../tex_main/NEMO_manual]{subfiles}
2\begin{document}
3% ================================================================
4% Appendix D Ñ Coding Rules
5% ================================================================
6\chapter{Coding Rules}
7\label{apdx:D}
8\minitoc
9
10\newpage
11$\ $\newline    % force a new ligne
12$\ $\newline    % force a new ligne
13
14
15A "model life" is more than ten years.
16Its software, composed of a few hundred modules, is used by many people who are scientists or students and
17do not necessarily know every aspect of computing very well.
18Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
19produces fewer bugs and is easier to maintain.
20Therefore, it is essential that the model development follows some rules:
21
22- well planned and designed
23
24- well written
25
26- well documented (both on- and off-line)
27
28- maintainable
29
30- easily portable
31
32- flexible.
33
34To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
35named DOCTOR \citep{Gibson_TR86}.
36These rules present some advantages like:
37
38- to provide a well presented program
39
40- to use rules for variable names which allow recognition of their type
41(integer, real, parameter, local or shared variables, etc. ).
42
43This facilitates both the understanding and the debugging of an algorithm.
44
45% ================================================================
46% The program structure
47% ================================================================
48\section{Program structure}
49\label{sec:D_structure}
50
51Each program begins with a set of headline comments containing:
52
53- the program title
54
55- the purpose of the routine
56
57- the method and algorithms used
58
59- the detail of input and output interfaces
60
61- the external routines and functions used (if they exist)
62
63- references (if they exist)
64
65- the author name(s), the date of creation and any updates.
66
67- Each program is split into several well separated sections and
68sub-sections with an underlined title and specific labelled statements.
69
70- A program has not more than 200 to 300 lines.
71
72A template of a module style can be found on the NEMO depository in the following file:
73NEMO/OPA\_SRC/module\_example.
74% ================================================================
75% Coding conventions
76% ================================================================
77\section{Coding conventions}
78\label{sec:D_coding}
79
80- Use of the universal language \textsc{Fortran} 90, and try to avoid obsolescent features like statement functions,
81do not use GO TO and EQUIVALENCE statements.
82
83- A continuation line begins with the character {\&} indented by three spaces compared to the previous line,
84while the previous line ended with the character {\&}.
85
86- All the variables must be declared.
87The code is usually compiled with implicit none.
88 
89- Never use continuation lines in the declaration of a variable.
90When searching a variable in the code through a \textit{grep} command, the declaration line will be found.
91
92- In the declaration of a PUBLIC variable, the comment part at the end of the line should start with
93the two characters "\verb?!:?".
94The following UNIX command, \\
95\verb?grep var_name *90 \ grep \!: ? \\
96will display the module name and the line where the var\_name declaration is.
97
98- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF statements.
99
100- use a space after a comma, except when it appears to separate the indices of an array.
101
102- use call to ctl\_stop routine instead of just a STOP.
103
104
105\newpage
106% ================================================================
107% Naming Conventions
108% ================================================================
109\section{Naming conventions}
110\label{sec:D_naming}
111
112The purpose of the naming conventions is to use prefix letters to classify model variables.
113These conventions allow the variable type to be easily known and rapidly identified.
114The naming conventions are summarised in the Table below:
115
116
117%--------------------------------------------------TABLE--------------------------------------------------
118\begin{table}[htbp]  \label{tab:VarName}
119\begin{center}
120\begin{tabular}{|p{45pt}|p{35pt}|p{45pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|}
121\hline  Type \par / Status &   integer&   real&   logical &   character  & structure &   double \par precision&   complex \\ 
122\hline
123public  \par or  \par module variable& 
124\textbf{m n} \par \textit{but not} \par \textbf{nn\_ np\_}& 
125\textbf{a b e f g h o q r} \par \textbf{t} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& 
126\textbf{l} \par \textit{but not} \par \textbf{lp ld} \par \textbf{ ll ln\_}& 
127\textbf{c} \par \textit{but not} \par \textbf{cp cd} \par \textbf{cl cn\_}& 
128\textbf{s} \par \textit{but not} \par \textbf{sd sd} \par \textbf{sl sn\_}& 
129\textbf{d} \par \textit{but not} \par \textbf{dp dd} \par \textbf{dl dn\_}& 
130\textbf{y} \par \textit{but not} \par \textbf{yp yd} \par \textbf{yl yn} \\
131\hline
132dummy \par argument& 
133\textbf{k} \par \textit{but not} \par \textbf{kf}& 
134\textbf{p} \par \textit{but not} \par \textbf{pp pf}& 
135\textbf{ld}& 
136\textbf{cd}& 
137\textbf{sd}& 
138\textbf{dd}& 
139\textbf{yd} \\
140\hline
141local \par variable& 
142\textbf{i}& 
143\textbf{z}& 
144\textbf{ll}& 
145\textbf{cl}& 
146\textbf{sl}& 
147\textbf{dl}& 
148\textbf{yl} \\
149\hline
150loop \par control& 
151\textbf{j} \par \textit{but not} \par \textbf{jp}& 
152& 
153& 
154&
155& 
156& 
157 \\
158\hline
159parameter& 
160\textbf{jp np\_}& 
161\textbf{pp}& 
162\textbf{lp}& 
163\textbf{cp}& 
164\textbf{sp}& 
165\textbf{dp}& 
166\textbf{yp} \\
167\hline
168
169namelist&
170\textbf{nn\_}& 
171\textbf{rn\_}& 
172\textbf{ln\_}& 
173\textbf{cn\_}& 
174\textbf{sn\_}& 
175\textbf{dn\_}& 
176\textbf{yn\_}
177\\
178\hline
179CPP \par macro& 
180\textbf{kf}& 
181\textbf{fs} \par & 
182& 
183&
184& 
185& 
186 \\
187\hline
188\end{tabular}
189\label{tab:tab1}
190\end{center}
191\end{table}
192%--------------------------------------------------------------------------------------------------------------
193
194N.B. Parameter here, in not only parameter in the \textsc{Fortran} acceptation,
195it is also used for code variables that are read in namelist and should never been modified during a simulation.
196It is the case, for example, for the size of a domain (jpi,jpj,jpk).
197
198\newpage
199% ================================================================
200% The program structure
201% ================================================================
202%\section{Program structure}
203%abel{sec:Apdx_D_structure}
204
205%To be done....
206\end{document}
Note: See TracBrowser for help on using the repository browser.