% ================================================================ % Chapter Ñ Appendix D : Coding Rules % ================================================================ \chapter{Appendix D : Coding Rules} \label{Apdx_D} \minitoc The "model life" is about ten years and its software, composed by about one hundred programs, is used by many people who are scientists or students and do not necessary know very well all computer aspects. Moreover, a well thought-out programme is easy to read and understand, less difficult to modify, produces fewer bugs and is easier to maintain. Therefore, it is essential that the model development follows some rules : - well planned and designed - well written - well documented (both on- and off-line) - maintainable - easily portable - flexible. To satisfy part of these aims, OPA is written with a coding standard which is close to the ECMWF rule, named DOCTOR [Gibson,1986]. These rules present some advantages like : - to provide a well presented program - to enable the extraction of several levels of on-line documentation - to use rules for variable names which allow recognition of their type (integer, real, parameter, common variables, etc. ) so that debugging is facilitated. \textbf{The program structure} Each program begins with a set of headline comments containing : - the program title - the purpose of the routine - the method and algorithms used - the detail of input and output interfaces - the external routines and functions used (if exist) - references (if exist) - the author name (s), the date of creation and of updates. - Each program is splitted into several well separated sections and sub-sections with a underlined title and specific labelled statements. - A program has not more than 200 to 300 lines. \textbf{Coding conventions} - Use of the universal language \textsc{Fortran} 5 ANSI 77, with non standard extensions, NAMELIST and \textsc{Fortran} 90 (matrix resolution algorithm), and some well-identified particular statements or functions for weak and massive parallelism, and vectorization - A comment line begins with a uppercase character C at the first column. A space line must have a C. For the on-line documentation, comments are classified into three levels : Overview, triggered by CCC in columns 1 to 3. Only the title and the purpose of the program are identified like that. This overview documentation can be extracted by the UNIX function : grep -e '\^{}CCC' * External, triggered by CC in columns 1 to 2, and which correspond to headlines of each programme, extracted by : grep -e '\^{}CC' * Internal which are all the comments, extracted by : grep -e '\^{}C' * - Statements GO TO, EQUIVALENCE are forbidden. - A section is numbered with labels which are in agreement with the paragraph label and increase from the begin to the end of routine. Labels of a hundred ( 200, 201.. 220..) are reserved to a unique section. The \textsc{Fortran} 90 extension syntax DO/ENDDO is used except for multitasked do-loop. In this case labels 1000, 2000, ... are used. The FORMAT statement are labelled with numbers in the range 9000 to 9999. - A continuation line begins with the character {\$} in column 6. - All statements begin in column 7 with the following gaps : 2 spaces toward the right in a DO loop. 4 spaces toward the right in IF, ELSEIF, ELSE and ENDIF statements, with only 2 spaces for ELSE and ELSEIF lines. All IF statement must be followed by a ELSE statement. Some spaces in the continuation line for alignment. - Use of different labels for each DO loop statement. - STOP must be well documented with the name of the subroutine or a number. \textbf{Naming Conventions.} The purpose of the naming conventions is to use prefix letters to classify model variables. These conventions allow to know easily the variable type and to identify them rapidly: %--------------------------------------------------TABLE-------------------------------------------------- \begin{table}[htbp] \begin{center} \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|} \hline Type \par / \par Status & integer& real& logical & character& double \par precision& complex \\ \hline global \par or \par common& \textbf{m n} \par \textit{but not } \par \textbf{nam}& \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{sf}& \textbf{l} \par \textit{but not} \par \textbf{lp ld ll}& \textbf{c} \par \textit{but not} \par \textbf{cp cd cl } \par \textbf{com cim}& \textbf{d} \par \textit{but not} \par \textbf{dp dd dl}& \textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\ \hline dummy \par argument& \textbf{k} \par \textit{but not} \par \textbf{kf}& \textbf{p} \par \textit{but not} \par \textbf{pp pf}& \textbf{ld}& \textbf{cd}& \textbf{dd}& \textbf{yd} \\ \hline local \par variable& \textbf{i}& \textbf{z}& \textbf{ll}& \textbf{cl}& \textbf{cd}& \textbf{yl} \\ \hline loop \par control& \textbf{j} \par \textit{but not } \par \textbf{jp}& & & & & \\ \hline parameter& \textbf{jp}& \textbf{pp}& \textbf{lp}& \textbf{cp}& \textbf{dp}& \textbf{yp} \\ \hline statement \par function& \textbf{kf}& \textbf{sf} \par & & & & \\ \hline \end{tabular} \label{tab1} \end{center} \end{table} %-------------------------------------------------------------------------------------------------------------- \textbf{References} {\small Gibson, J. K., 1986: Standard software development and maintenance. }{\small \textit{Tech. memorandum}}{\small , Operational Dep., ECMWF, Reading, UK.}