Changeset 11525 for NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/global/coding_rules.tex
- Timestamp:
- 2019-09-10T16:18:42+02:00 (5 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/global/coding_rules.tex
r11512 r11525 3 3 \label{apdx:coding} 4 4 5 \ minitoc5 \chaptertoc 6 6 7 7 \newpage … … 13 13 produces fewer bugs and is easier to maintain. 14 14 Therefore, it is essential that the model development follows some rules: 15 15 16 \begin{itemize} 16 17 18 19 20 21 17 \item well planned and designed 18 \item well written 19 \item well documented (both on- and off-line) 20 \item maintainable 21 \item easily portable 22 \item flexible. 22 23 \end{itemize} 23 24 24 25 To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules, 25 named DOCTOR \citep{gibson_rpt86}. 26 named DOCTOR \citep{gibson_rpt86}. 26 27 These rules present some advantages like: 28 27 29 \begin{itemize} 28 \item to provide a well presented program 29 \item to use rules for variable names which allow recognition of their type 30 (integer, real, parameter, local or shared variables, etc. ). 30 \item to provide a well presented program 31 \item to use rules for variable names which allow recognition of their type (integer, real, parameter, local or shared variables, etc. ). 31 32 \end{itemize} 32 33 … … 45 46 46 47 This work is based on the coding conventions in use for the Community Climate System Model 47 \footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}}, 48 \footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}}, 48 49 the previous version of this document (``FORTRAN coding standard in the OPA System'') and 49 50 the expertise of the \NEMO System Team. … … 51 52 52 53 \begin{itemize} 53 54 55 54 \item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code; 55 \item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code; 56 \item The package rules to go a step further by improving the reliability of the whole and 56 57 interfaces between routines and modules. 57 58 \end{itemize} … … 79 80 80 81 \begin{itemize} 81 82 83 84 \item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries 85 86 87 82 \item \path{SBC} surface module 83 \item \path{IOM} management of the I/O 84 \item \path{NST} interface to AGRIF (nesting model) for dynamics and biogeochemistry 85 \item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries 86 \item \path{C1D} 1D (vertical) configuration for dynamics, sea-ice and biogeochemistry 87 \item \path{OFF} off-line module: passive tracer or biogeochemistry alone 88 \item \path{...} 88 89 \end{itemize} 89 90 … … 292 293 complex \\ 293 294 \hline 294 public \par or \par module variable & 295 \textbf{m n} \par \textit{but not} \par \textbf{nn\_} & 295 public \par or \par module variable & 296 \textbf{m n} \par \textit{but not} \par \textbf{nn\_} & 296 297 \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_} & 297 298 \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_} & … … 301 302 \hline 302 303 dummy \par argument & 303 \textbf{k} \par \textit{but not} \par \textbf{kf} & 304 \textbf{p} \par \textit{but not} \par \textbf{pp pf} & 304 \textbf{k} \par \textit{but not} \par \textbf{kf} & 305 \textbf{p} \par \textit{but not} \par \textbf{pp pf} & 305 306 \textbf{ld} & 306 307 \textbf{cd} & … … 309 310 \hline 310 311 local \par variable & 311 \textbf{i} & 312 \textbf{i} & 312 313 \textbf{z} & 313 314 \textbf{ll} & … … 333 334 \hline 334 335 namelist & 335 \textbf{nn\_} & 336 \textbf{nn\_} & 336 337 \textbf{rn\_} & 337 338 \textbf{ln\_} & … … 748 749 Below is a list of features to avoid: 749 750 \begin{itemize} 750 \item 751 \forcode{COMMON} block 751 \item \forcode{COMMON} block 752 752 (use the declaration part of \forcode{MODULE} instead) 753 \item 754 \forcode{EQUIVALENCE} 753 \item \forcode{EQUIVALENCE} 755 754 (use \forcode{POINTER} or derived data type instead to form data structure) 756 \item 757 Assigned and computed \forcode{GOTO} 755 \item Assigned and computed \forcode{GOTO} 758 756 (use the \forcode{CASE} construct instead) 759 \item 760 Arithmetic \forcode{IF} statement 757 \item Arithmetic \forcode{IF} statement 761 758 (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or 762 759 \forcode{SELECT CASE} construct instead) 763 \item 764 Labelled \forcode{DO} construct 760 \item Labelled \forcode{DO} construct 765 761 (use unlabelled \forcode{END DO} instead) 766 \item 767 \forcode{FORMAT} statement 762 \item \forcode{FORMAT} statement 768 763 (use character parameters or 769 764 explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead) 770 \item 771 \forcode{GOTO} and \forcode{CONTINUE} statements 765 \item \forcode{GOTO} and \forcode{CONTINUE} statements 772 766 (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or 773 767 a contained ?) 774 \item 775 \forcode{PAUSE} 776 \item 777 \forcode{ENTRY} statement: a sub-program must only have one entry point. 778 \item 779 \forcode{RETURN} is obsolete and so not necessary at the end of program units 780 \item 781 \forcode{FUNCTION} statement 782 \item 783 Avoid functions with side effects. 768 \item \forcode{PAUSE} 769 \item \forcode{ENTRY} statement: a sub-program must only have one entry point. 770 \item \forcode{RETURN} is obsolete and so not necessary at the end of program units 771 \item \forcode{FUNCTION} statement 772 \item Avoid functions with side effects. 784 773 \footnote{ 785 774 First, the code is easier to understand, if you can rely on … … 790 779 This is especially important on massive parallel and as well on vector machines. 791 780 } 792 \item 793 \forcode{DATA} and \forcode{BLOCK DATA} 781 \item \forcode{DATA} and \forcode{BLOCK DATA} 794 782 (use initialisers) 795 783 \end{itemize} 796 784 785 %% Imported from introduction 786 %%gm To be put somewhere else .... 787 %%nm We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols) 788 %% http://en.wikibooks.org/wiki/LaTeX/Glossary 789 %\noindent CPP keys and namelists are used as inputs to the code. 790 791 %\noindent \index{CPP keys} CPP keys 792 793 %Some CPP keys are implemented in the \fortran code to allow code selection at compiling step. 794 %This selection of code at compilation time reduces the reliability of the whole platform since 795 %it changes the code from one set of CPP keys to the other. 796 %It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time. 797 %Usual coding looks like: 798 799 %\begin{forlines} 800 %#if defined key_option1 801 % ! This part of the \fortran code will be active 802 % ! only if key_option1 is activated at compiling step 803 %#endif 804 %\end{forlines} 805 806 %\noindent \index{Namelist} Namelists 807 808 %The namelist allows to input variables (character, logical, real and integer) into the code. 809 %There is one namelist file for each component of \NEMO\ (dynamics, sea-ice, biogeochemistry...) 810 %containing all the \fortran namelists needed. 811 %The implementation in \NEMO\ uses a 2-step process. 812 %For each \fortran namelist, two files are read: 813 814 %\begin{enumerate} 815 %\item 816 % A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first. 817 % This file contains all the namelist variables which are initialised to default values 818 %\item 819 % A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards. 820 % This file contains only the namelist variables which are changed from default values, and overwrites those. 821 %\end{enumerate} 822 %A template can be found in \path{NEMO/OPA_SRC/module.example}. 823 %The effective namelist, taken in account during the run, is stored at execution time in 824 %an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file. 825 %%gm end 826 827 %%nm: Add some words on the \NEMO\ dependencies 828 %The model is implemented in \fninety, with preprocessing (C pre-processor). 829 %It runs under UNIX. 830 %It is optimized for vector computers and parallelised by domain decomposition with MPI. 831 %All input and output is done in NetCDF (Network Common Data Format) with a optional direct access format for output. 832 %To ensure the clarity and readability of the code it is necessary to follow coding rules. 833 %The coding rules for OPA include conventions for naming variables, 834 %with different starting letters for different types of variables (real, integer, parameter\ldots). 835 %Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available . 836 837 %The model is organized with a high internal modularity based on physics. 838 %For example, each trend (\ie, a term in the RHS of the prognostic equation) for momentum and tracers 839 %is computed in a dedicated module. 840 %To make it easier for the user to find his way around the code, the module names follow a three-letter rule. 841 %For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion. 842 %The complete list of module names is presented in \autoref{apdx:coding}. %====>>>> to be done ! 843 %Furthermore, modules are organized in a few directories that correspond to their category, 844 %as indicated by the first three letters of their name (\autoref{tab:chapters}).
Note: See TracChangeset
for help on using the changeset viewer.
