Changes between Version 8 and Version 9 of doc/tec/developerrules/palmstandard
- Timestamp:
- Nov 6, 2018 4:41:59 PM (6 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
doc/tec/developerrules/palmstandard
v8 v9 1 1 = PALM coding rules = 2 Why to follow some standards? - Because everyone has her/his own programming style, sort of a dialect, making it difficult for other developers to understand, extend, debug, or optimize the code. So what do we do? We learn and apply the coding standard to make PALM more easily readable for all current and future developers. Let's all work on that together. We are aware that the PALM core doesn't completely comply with the following rules yet, but we are working on that. 3 \\ 2 '''Why to follow some standards?'''\\\\ 3 Because everyone has her/his own programming style, sort of a dialect, making it difficult for other developers to understand, extend, debug, or optimize the code. So what do we do? We learn and apply the coding standard to make PALM more easily readable for all current and future developers. Let's all work on that together. We are aware that the PALM core doesn't completely comply with the following rules yet, but we are working on that. 4 \\\\ 4 5 Formulated rules and specifications are based on the specifications given for the ocean dynamics model [add-new-link-to NEMO]. 5 6 Other work that influenced the development of this standard are [add-link Community Climate System Model], [add-link Software Developer's Guide], [add-link Report on Column Physics Standards], and [add-link European Standards For Writing and Documenting Exchangeable FORTRAN 90 Code]. 6 7 7 8 \\ 8 == (1) General language & form requirements == 9 = (1) General hints & requirements = 10 == (1.1) Language == 9 11 * FORTRAN-2003 standard (all FORTRAN compilers can handle this, FORTRAN-2008 standard not yet supported by all compilers) 10 12 * Use English language only 11 13 * Use ASCII characters only 12 14 * Use SI units as physical units 13 * Line length limit: 80 characters (soft) | 120 characters (hard) --> Optimize readability (FORTRAN-2003 standard allows '''max. 132''' characters)14 15 15 16 || '''AVOID''' || '''USE INSTEAD''' || 16 17 || COMMON blocks || ... || 17 18 19 == (1.2) Implementing new features to PALM == 20 * module structure (template) 21 * available interfaces in the PALM core 22 18 23 \\ 19 == (2) Indenting, spaces & line breaks == 24 = (2) Documenting & commenting = 25 26 \\ 27 = (3) Naming conventions = 28 29 \\ 30 = (4) Formatting & sorting = 31 Line length limit: '''80''' characters (soft) | '''120''' characters (hard). The absolute limit for compilers is '''132''' characters! 32 33 == (4.1) Indenting, spaces & line breaks == 20 34 '''__General module/subroutine structure''' 21 35 (see Fig. 1) … … 25 39 '''Fig. 1''' Indention example with highlighted whitespaces. Click to enlarge. 26 40 }}} 27 28 41 * '''0 whitespace''' in front of pre-processor directives 29 42 * '''1 whitespace''' before MODULE, CONTAINS, SUBROUTINE (= first indention level) 30 * '''+3 whitespaces''' for all following indention levels \\(only exception: ONLY list in USE statements '''+4 whitespaces''')\\ 31 43 * '''+3 whitespaces''' for all following indention levels \\(only exception: ONLY list in USE statements '''+4 whitespaces''')\\\\ 32 44 * '''1 whitespace''' between individual strings, and between strings and symbols/numbers 33 45 * '''1 whitespace''' after ''','''\\(only exception: '''0 whitespace''' between array dimensions) 34 46 * '''1 whitespace''' before '''::''' \\(at minimum, see Sect. [#align Alignment]) 35 * '''2 whitespace''' after ''':''' and '''::'''\\ 36 37 * ''' 1 blank line''' between enclosed blocks of instructions, assignments, clauses, statements, etc.47 * '''2 whitespace''' after ''':''' and '''::'''\\\\ 48 * '''1 blank line''' between enclosed/unrelated blocks of instructions, assignments, clauses, statements, etc. 49 * '''2 blank lines''' in front of each SUBROUTINE within a MODULE 38 50 * '''&''' character for line continuation at position 80 (minimum), max at position 120 39 51 … … 51 63 '''Fig. 2''' Indention & whitespaces in loops. Click to enlarge. 52 64 }}} 53 54 * In general: '''1 whitespace''' everywhere and '''3 whitespace''' for indention levels 65 * In general: '''1 whitespace''' everywhere and '''3 whitespace''' for each indention level 55 66 * But: '''2 whitespace'''\\ 56 67 * between '''DO''' and '''loop index''' … … 60 71 61 72 \\\\\\\\\\ 62 == ( 3) Alignment ==73 == (4.2) Alignment == 63 74 (see Fig. 3) 64 75 {{{ … … 71 82 * At least block-wise alignment for same type/group of declaration statement 72 83 * Alignment of message_string values 73 * Alignment of expressions between brackets (e.g. in '''IF ( ) THEN''' or in argument list in subroutine calls) 84 * Alignment of expressions between brackets (e.g. in '''IF ( ) THEN''' or in argument list of subroutine calls) 85 * Alignment of same level of mathematical expressions or array indices '''(missing in png)''' 74 86 75 87 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 76 == Alphabetical sorting ==88 == (4.3) Alphabetical sorting == 77 89 except for CALLs to modules/subroutines 78 90 79 91 == Lower/upper case == 80 92 81 == Commenting == 93 == Commenting & documentation == 94 Documentation consists of putting information both inside and outside the source code. 95 Comments should give a good idea of what the code does and where to look for any special activity. 96 97 '''Doxygen format''' 98 * Declaration !< Description 99 * see file header 100 * @author etc. 101 * MODULE/SUBROUTINE description !> 102 103 '''Header section''' 104 * todos, notes, author,.... 105 106 '''Inside the code''' 107 * Examples.png.. 108 * Avoid superfluous comments, such as\\ {{{a = a + 1 ! Increment a by one}}} 109 * Example for multiple-line declaration comment 110 ! 111 !-- Text starts at same position as indented code to be described 112 113 '''Outside the code''' 114 115 = (X) Coding = 116 == (X.1) Variable & parameter declarations == 117 * clear structure in declaration part (USE, IMPLICIT NONE, declarations, SAVE, PRIVATE, PUBLIC list_of_public_variables) 118 * for long lists form groups 119 * one declaration line per variable 82 120 83 121 == Naming conventions == 122 Use clear, unambiguous naming in '''lower-case letters''', with individual words separated by underscore. 123 * MODULE/SUBROUTINE: name is constructed (if applicable) as verb followed by object, e.g.\\ 124 {{{land_surface_model}}} or {{{read_restart_data}}} 125 * MODULE/SUBROUTINE files: <filename>.f90 --> MODULE <filename> ... END MODULE <filename> (simplification of Make process) 126 * Functions: names provide information about the value it is expected to return, e.g.\\ 127 {{{solar_zenith_angle( )}}} 128 * Variables & constants: names are readable, memorable and descriptive 129 * LOGICAL (boolean) variables: give names that imply\\ 130 {{{TRUE}}} or {{{FALSE}}} 131 132 '''PROHIBITED:''' 133 * Names that may clash with the operating system or language intrinsics, e.g.\\ 134 {{{read( )}}} or {{{access( )}}} 135 * One-letter variable names (only allowed for basic flow variables like velocities (u, v, w), humidity (q) or turbulent kinetic energy (e), as well as loop or other counters (e.g. i, j, k)) 84 136 85 137 == Allowed operators == … … 88 140 89 141 == Preprocessor directives == 142 PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered my most FORTRAN compilers. 143 Only few pre-processor directives are used in PALM, and activated by the {{{%cpp_options}}} variable in the .palm.config.<configuration_identifier> file. 90 144 91 == Declaration statements == 92 * for long lists form groups 145 Table or link to other page 146 || '''flag''' || '''description''' || 147 || __parallel || .... || 148 149 Use this syntax (starting at first character of a line): 150 {{{#if defined(__parallel) 151 some code 152 #endif}}} 153 together with the standard logical operators '''!''' (instead of .NOT.), '''||''' (instead of .OR.), '''&&''' (instead of .AND.), e.g. 154 {{{#if ! defined(__parallel) && (__netcdf)}}} 155 156 157 93 158 94 159 == File header == … … 98 163 * Finally, involved authors are included, followed by a description of the purpose and functions of the module. If necessary, TODOs, notes and known bugs can be added. The "!>" indicate doxygen-readable comment lines, the "@" marks doxygen variables. 99 164 100 == Check compilation == 101 * no warning/error message should remain 165 == (X) Code structure == 166 * one module per file (only exception: modules.f90) 167 * clarify program entities, i.e. use {{{SUBROUTINE <name> ... END SUBROUTINE <name>}}}, same holds for INTERFACE, MODULE, PROGRAM 168 169 ------------------------- 170 == Error messages == 171 * Use message routine (explain parameters here...) 172 * I/O error conditions via IOSTAT (is this fail-safe for different compilers?) 173 174 175 == (X) Final steps == 176 '''Good practice''' 177 * no warning/error message should remain during compile (also try debug options) 178 179 '''Clean up''' 180 * PRINT/WRITE statements for debugging 181 * Check that all parameters are used
