[707] | 1 | % ================================================================ |
---|
| 2 | % Chapter Ñ Appendix D : Coding Rules |
---|
| 3 | % ================================================================ |
---|
| 4 | \chapter{Appendix D : Coding Rules} |
---|
| 5 | \label{Apdx_D} |
---|
| 6 | \minitoc |
---|
| 7 | |
---|
| 8 | |
---|
| 9 | The "model life" is about ten years and its software, composed by about one |
---|
| 10 | hundred programs, is used by many people who are scientists or students and |
---|
| 11 | do not necessary know very well all computer aspects. Moreover, a well |
---|
| 12 | thought-out programme is easy to read and understand, less difficult to |
---|
| 13 | modify, produces fewer bugs and is easier to maintain. Therefore, it is |
---|
| 14 | essential 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 | |
---|
| 28 | To satisfy part of these aims, OPA is written with a coding standard which |
---|
| 29 | is close to the ECMWF rule, named DOCTOR [Gibson,1986]. These rules present |
---|
| 30 | some 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 |
---|
| 38 | facilitated. |
---|
| 39 | |
---|
| 40 | \textbf{The program structure} |
---|
| 41 | |
---|
| 42 | Each 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 |
---|
| 59 | sub-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 |
---|
| 66 | standard extensions, NAMELIST and \textsc{Fortran} 90 (matrix resolution |
---|
| 67 | algorithm), and some well-identified particular statements or functions for |
---|
| 68 | weak and massive parallelism, and vectorization |
---|
| 69 | |
---|
| 70 | - A comment line begins with a uppercase character C at the first column. A |
---|
| 71 | space line must have a C. For the on-line documentation, comments are |
---|
| 72 | classified into three levels : |
---|
| 73 | |
---|
| 74 | Overview, triggered by CCC in columns 1 to 3. Only the title and the purpose |
---|
| 75 | of the program are identified like that. This overview documentation can be |
---|
| 76 | extracted by the UNIX function : grep -e '\^{}CCC' * |
---|
| 77 | |
---|
| 78 | External, triggered by CC in columns 1 to 2, and which correspond to |
---|
| 79 | headlines of each programme, extracted by : grep -e '\^{}CC' * |
---|
| 80 | |
---|
| 81 | Internal 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 |
---|
| 86 | paragraph label and increase from the begin to the end of routine. Labels of |
---|
| 87 | a hundred ( 200, 201.. 220..) are reserved to a unique section. The |
---|
| 88 | \textsc{Fortran} 90 extension syntax DO/ENDDO is used except for multitasked |
---|
| 89 | do-loop. In this case labels 1000, 2000, ... are used. The FORMAT statement |
---|
| 90 | are 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 | |
---|
| 96 | 2 spaces toward the right in a DO loop. |
---|
| 97 | |
---|
| 98 | 4 spaces toward the right in IF, ELSEIF, ELSE and ENDIF statements, with |
---|
| 99 | only 2 spaces for ELSE and ELSEIF lines. All IF statement must be followed |
---|
| 100 | by a ELSE statement. |
---|
| 101 | |
---|
| 102 | Some 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 | |
---|
| 110 | The purpose of the naming conventions is to use prefix letters to classify |
---|
| 111 | model variables. These conventions allow to know easily the variable type |
---|
| 112 | and 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 |
---|
| 120 | Type \par / \par Status & |
---|
| 121 | integer& |
---|
| 122 | real& |
---|
| 123 | logical & |
---|
| 124 | character& |
---|
| 125 | double \par precision& |
---|
| 126 | complex \\ |
---|
| 127 | \hline |
---|
| 128 | global \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 |
---|
| 136 | dummy \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 |
---|
| 144 | local \par variable& |
---|
| 145 | \textbf{i}& |
---|
| 146 | \textbf{z}& |
---|
| 147 | \textbf{ll}& |
---|
| 148 | \textbf{cl}& |
---|
| 149 | \textbf{cd}& |
---|
| 150 | \textbf{yl} \\ |
---|
| 151 | \hline |
---|
| 152 | loop \par control& |
---|
| 153 | \textbf{j} \par \textit{but not } \par \textbf{jp}& |
---|
| 154 | & |
---|
| 155 | & |
---|
| 156 | & |
---|
| 157 | & |
---|
| 158 | \\ |
---|
| 159 | \hline |
---|
| 160 | parameter& |
---|
| 161 | \textbf{jp}& |
---|
| 162 | \textbf{pp}& |
---|
| 163 | \textbf{lp}& |
---|
| 164 | \textbf{cp}& |
---|
| 165 | \textbf{dp}& |
---|
| 166 | \textbf{yp} \\ |
---|
| 167 | \hline |
---|
| 168 | statement \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 | |
---|