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

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

dev_r10164_HPC09_ESIWACE_PREP_MERGE: merge with trunk@10418, see #2133

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