New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Annex_D.tex in branches/nemo_v3_3_beta/DOC/TexFiles/Chapters – NEMO

source: branches/nemo_v3_3_beta/DOC/TexFiles/Chapters/Annex_D.tex @ 2414

Last change on this file since 2414 was 2414, checked in by gm, 13 years ago

v3.3beta: #658 Documentation phasing with the 3.3 - C1D & other minor staff

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