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 trunk/NEMO/DOC/BETA/Chapters – NEMO

source: trunk/NEMO/DOC/BETA/Chapters/Annex_D.tex @ 707

Last change on this file since 707 was 707, checked in by smasson, 16 years ago

error during changeset:705... related to ticket:1

  • Property svn:executable set to *
File size: 5.5 KB
Line 
1% ================================================================
2% Chapter Ñ Appendix D : Coding Rules
3% ================================================================
4\chapter{Appendix D : Coding Rules}
5\label{Apdx_D}
6\minitoc
7
8
9The "model life" is about ten years and its software, composed by about one
10hundred programs, is used by many people who are scientists or students and
11do not necessary know very well all computer aspects. Moreover, a well
12thought-out programme is easy to read and understand, less difficult to
13modify, produces fewer bugs and is easier to maintain. Therefore, it is
14essential that the model development follows some rules :
15
16- well planned and designed
17
18- well written
19
20- well documented (both on- and off-line)
21
22- maintainable
23
24- easily portable
25
26- flexible.
27
28To satisfy part of these aims, OPA is written with a coding standard which
29is close to the ECMWF rule, named DOCTOR [Gibson,1986]. These rules present
30some advantages like :
31
32- to provide a well presented program
33
34- to enable the extraction of several levels of on-line documentation
35
36- to use rules for variable names which allow recognition of their type
37(integer, real, parameter, common variables, etc. ) so that debugging is
38facilitated.
39
40\textbf{The program structure}
41
42Each program begins with a set of headline comments containing :
43
44- the program title
45
46- the purpose of the routine
47
48- the method and algorithms used
49
50- the detail of input and output interfaces
51
52- the external routines and functions used (if exist)
53
54- references (if exist)
55
56- the author name (s), the date of creation and of updates.
57
58- Each program is splitted into several well separated sections and
59sub-sections with a underlined title and specific labelled statements.
60
61- A program has not more than 200 to 300 lines.
62
63\textbf{Coding conventions}
64
65- Use of the universal language \textsc{Fortran} 5 ANSI 77, with non
66standard extensions, NAMELIST and \textsc{Fortran} 90 (matrix resolution
67algorithm), and some well-identified particular statements or functions for
68weak and massive parallelism, and vectorization
69
70- A comment line begins with a uppercase character C at the first column. A
71space line must have a C. For the on-line documentation, comments are
72classified into three levels :
73
74Overview, triggered by CCC in columns 1 to 3. Only the title and the purpose
75of the program are identified like that. This overview documentation can be
76extracted by the UNIX function : grep -e '\^{}CCC' *
77
78External, triggered by CC in columns 1 to 2, and which correspond to
79headlines of each programme, extracted by : grep -e '\^{}CC' *
80
81Internal which are all the comments, extracted by : grep -e '\^{}C' *
82
83- Statements GO TO, EQUIVALENCE are forbidden.
84
85- A section is numbered with labels which are in agreement with the
86paragraph label and increase from the begin to the end of routine. Labels of
87a hundred ( 200, 201.. 220..) are reserved to a unique section. The
88\textsc{Fortran} 90 extension syntax DO/ENDDO is used except for multitasked
89do-loop. In this case labels 1000, 2000, ... are used. The FORMAT statement
90are labelled with numbers in the range 9000 to 9999.
91
92- A continuation line begins with the character {\$} in column 6.
93
94- All statements begin in column 7 with the following gaps :
95
962 spaces toward the right in a DO loop.
97
984 spaces toward the right in IF, ELSEIF, ELSE and ENDIF statements, with
99only 2 spaces for ELSE and ELSEIF lines. All IF statement must be followed
100by a ELSE statement.
101
102Some spaces in the continuation line for alignment.
103
104- Use of different labels for each DO loop statement.
105
106- STOP must be well documented with the name of the subroutine or a number.
107
108\textbf{Naming Conventions.}
109
110The purpose of the naming conventions is to use prefix letters to classify
111model variables. These conventions allow to know easily the variable type
112and to identify them rapidly:
113
114
115%--------------------------------------------------TABLE--------------------------------------------------
116\begin{table}[htbp]
117\begin{center}
118\begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
119\hline
120Type \par / \par Status & 
121integer& 
122real& 
123logical & 
124character& 
125double \par precision& 
126complex \\
127\hline
128global \par or \par common& 
129\textbf{m n} \par \textit{but not } \par \textbf{nam}& 
130\textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{sf}& 
131\textbf{l} \par \textit{but not} \par \textbf{lp ld ll}& 
132\textbf{c} \par \textit{but not} \par \textbf{cp cd cl } \par \textbf{com cim}& 
133\textbf{d} \par \textit{but not} \par \textbf{dp dd dl}& 
134\textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
135\hline
136dummy \par argument& 
137\textbf{k} \par \textit{but not} \par \textbf{kf}& 
138\textbf{p} \par \textit{but not}  \par \textbf{pp pf}& 
139\textbf{ld}& 
140\textbf{cd}& 
141\textbf{dd}& 
142\textbf{yd} \\
143\hline
144local \par variable& 
145\textbf{i}& 
146\textbf{z}& 
147\textbf{ll}& 
148\textbf{cl}& 
149\textbf{cd}& 
150\textbf{yl} \\
151\hline
152loop \par control& 
153\textbf{j} \par \textit{but not } \par \textbf{jp}& 
154& 
155& 
156& 
157& 
158 \\
159\hline
160parameter& 
161\textbf{jp}& 
162\textbf{pp}& 
163\textbf{lp}& 
164\textbf{cp}& 
165\textbf{dp}& 
166\textbf{yp} \\
167\hline
168statement \par function& 
169\textbf{kf}& 
170\textbf{sf} \par & 
171& 
172& 
173& 
174 \\
175\hline
176\end{tabular}
177\label{tab1}
178\end{center}
179\end{table}
180%--------------------------------------------------------------------------------------------------------------
181
182\textbf{References}
183
184{\small Gibson, J. K., 1986: Standard software development and maintenance. }{\small \textit{Tech. memorandum}}{\small , Operational Dep., ECMWF, Reading, UK.}
185
Note: See TracBrowser for help on using the repository browser.