Changes between Version 12 and Version 13 of doc/tec/developerrules/palmstandard
- Timestamp:
- Nov 12, 2018 4:56:05 PM (6 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
doc/tec/developerrules/palmstandard
v12 v13 1 1 = PALM coding rules = 2 '''Why to follow some standards?'''\\\\ 2 = (0) Why to follow some standards? = 3 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 \\\\ … … 13 13 * Use '''ASCII''' characters only 14 14 * Use '''SI units''' as physical units 15 * '''NO''' use of tab characters (only exception: Makefile), because depending on the text editor, the code indentations might be ruined 15 * Line-length limit '''132 characters''' (absolute limit for most compilers) 16 * '''NO''' use of tab characters (only exception: Makefile), because depending on the text editor, the code indentations might be corrupted. 16 17 17 18 || '''AVOID''' || '''USE INSTEAD''' || … … 25 26 \\ 26 27 = (2) Documenting & commenting = 27 Documentation consists of putting information both internally and externally of the source code. Comments should give a good idea of what the code does and where to look for any special activity. PALM supports the use of [link-to Doxygen], a tool for generating documentation and flow charts from annotated source code. This requires some special formatting, as described below. 28 29 == (2.1) File header section == 30 * todos, notes, author,.... 31 * Declaration !< Description 32 * see file header 33 * @author etc. 34 * MODULE/SUBROUTINE description !> 28 {{{ 29 #!div style="align:'left'; width: 450px; border: 0px solid; float:right" 30 [[Image(rules_header.png, 450px, right, margin-right=2, margin-top=0, border=0)]]\\ 31 '''Fig. 4''' PALM source-code header example. Click to enlarge. 32 }}} 33 Documentation consists of putting information both internally and externally of the source code. Comments should give a good idea of what the code does and where to look for any special activity. PALM supports the use of [wiki:doc/tec/doxygen Doxygen], a tool for generating documentation and flow charts from annotated source code. This requires some special formatting, as described below. 34 35 == (2.1) External documentation == 36 You are in the middle of it. We have an extensive online documentation wiki embedded into a [link-to trac] project management system, directly connected to the svn repository, allowing to [link-to-browser browse the PALM code] @ all its former and of course current revision in a web-based environment.\\\\ 37 Your carefully developed code can only be used, if there is a documentation that tells the PALM user how to use and steer the feature. All pages can be accessed from the main [link-to Documentation] page (see index on the left). There are pages for [wiki:doc#Modeldescription model/code description], and [wiki:doc#Usermanual user-manual] pages that explain about model steering, data analysis and debugging. Have a look at and discuss with us where your documentation material fits in best. 35 38 36 39 == (2.2) Internal documentation == 37 (one variable per declaration statement!)\\\\ 40 '''File header section''' 41 (see Fig. 4) 42 a. Doxygen command for FORTRAN file name ('''!>''' starts a doxygen command line) 43 b. PALM license section (you may have to add other licenses if allowedly implementing code from other models) 44 c. Revision comments (see [link-to svn branches and trunk committing]) 45 d. Doxygen command for listing authors of the module 46 e. Module description (give a brief description of about the modules purpose) 47 f. Another set of doxygen commands for listing todos, notes and know bugs 48 38 49 '''Description of variables''' 39 * Short description for each declared variable, comments should be aligned per declaration block\\ 50 (one variable per declaration statement!) 51 * Short description for each declared variable, comments should be aligned per declaration block 52 * At minimum, 2 whitespace before '''!<''' 53 * '''!<''' character introduces doxygen comment 40 54 {{{ 41 55 LOGICAL :: conserve_water_content = .TRUE. !< open or closed bottom surface for the soil model … … 45 59 REAL(wp) :: deep_soil_temperature = 9999999.9_wp !< Deep soil temperature (K) 46 60 }}} 47 * If comment reaches over 1 20 characters (hard linelimit), break comment into (max.) 2 lines61 * If comment reaches over 132 characters (hard limit), break comment into (max.) 2 lines 48 62 {{{ 49 63 LOGICAL :: conserve_water_content = .TRUE. !< open or closed bottom surface for the soil model … … 58 72 !-- 59 73 }}} 60 * Comment text always starts at same position as indented code to be described, and break text into several lines if '''> 80characters''' are reached74 * Comment text always starts at same position as the indented code to be described, and break text into several lines if '''> 132 characters''' are reached 61 75 {{{ 62 76 DO j = nys, nyn … … 78 92 }}} 79 93 80 == (2.3) External documentation == 81 You are in the middle of it. We have an extensive online documentation wiki embedded into a [link-to trac] project management system, directly connected to the svn repository, allowing to [link-to-browser browse the PALM code] @ all its former and of course current revision in a web-based environment.\\\\ 82 Your carefully developed code can only be used, if there is a documentation that tells the PALM user how to use and steer the feature. All pages can be accessed from the main [link-to Documentation] page (see index on the left). There are pages for [wiki:doc#Modeldescription model/code description], and [wiki:doc#Usermanual user-manual] pages that explain about model steering, data analysis and debugging. Have a look at and discuss with us where your documentation material fits in best. 94 83 95 84 96 … … 107 119 '''PROHIBITED:''' 108 120 * Names that may clash with the operating system or language intrinsic, e.g.\\ 109 {{{read( )}}} or {{{access( )}}}121 {{{read( )}}} or {{{access( )}}} 110 122 * 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)) 111 123 112 124 \\ 113 125 = (4) Formatting & sorting = 114 Line length limit: ''' 80''' characters (soft) | '''120''' characters (hard). The absolute limit for compilers is '''132''' characters!126 Line length limit: '''132''' characters (hard limit) 115 127 116 128 == (4.1) Indentation, spaces & line breaks == … … 132 144 * '''1 blank line''' between enclosed/unrelated blocks of instructions, assignments, clauses, statements, etc. 133 145 * '''2 blank lines''' in front of each SUBROUTINE within a MODULE 134 * place '''&''' character for line continuation at position 80 (minimum), max at position 120\\('''Note:''' FORTRAN-2003 defines a limit of 39 continuation lines)135 146 136 147 '''__Whitespaces between brackets''' … … 169 180 * Alignment of related code, e.g. in complex equations or setting of initial values for variables '''(missing in png)''' 170 181 171 \\\\172 182 == (4.3) Alphabetical sorting == 173 183 * Members in ONLY lists of USE statements (see e.g. Fig. 3) … … 178 188 179 189 180 181 = ( X) Coding =182 == ( X.1) Variable & parameter declarations ==190 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 191 = (5) Coding = 192 == (5.1) Variable & parameter declarations == 183 193 * clear structure in declaration part (USE, IMPLICIT NONE, declarations, SAVE, PRIVATE, PUBLIC list_of_public_variables) 184 194 * for long lists form groups 185 195 * one declaration line per variable 186 196 187 188 189 == Allowed operators == 197 == (5.2) Allowed operators == 190 198 * Use /=, <, <=, ==, >, >=, etc. as relational operators instead of .GE., .LT., etc. 191 199 * Use .AND., .OR., .NOT. as logical operators 192 200 193 == Preprocessor directives ==201 == (5.3) Preprocessor directives == 194 202 PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered my most FORTRAN compilers. 195 203 Only few pre-processor directives are used in PALM, and activated by the {{{%cpp_options}}} variable in the .palm.config.<configuration_identifier> file. … … 205 213 together with the standard logical operators '''!''' (instead of .NOT.), '''||''' (instead of .OR.), '''&&''' (instead of .AND.), e.g. 206 214 {{{#if ! defined(__parallel) && (__netcdf)}}} 207 208 209 210 211 == File header == 212 * Files always start with a doxygen-readable comment line including the FORTRAN file name. 213 * This is followed by the license section. If your code originates from another model, please clarify the license and permissions for this code to enter the PALM model system. It might be necessary in that case to add some more information to this header. 214 * The revisions section will later include short notes of the changes applied to a specific svn revision of this file. The {{{$Id$}}} string is required so that svn knows to automatically generate the respective time stamp for a revision (see existing SOURCE files).\\ 215 --> [link-to How to initialize Id keyword in svn] 216 * mention revision history and link to [How to commit] 217 * 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. 218 219 == (X) Code structure == 215 216 == (5.4) Code structure == 217 '''(move somewhere else)''' 220 218 * one module per file (only exception: modules.f90) 221 219 * clarify program entities, i.e. use {{{SUBROUTINE <name> ... END SUBROUTINE <name>}}}, same holds for INTERFACE, MODULE, PROGRAM 222 220 223 ------------------------- 224 == Error messages == 221 == (5.5) Error messages == 225 222 * Use message routine (explain parameters here...) 226 223 * I/O error conditions via IOSTAT (is this fail-safe for different compilers?) 227 224 228 == Code optimization ==225 == (5.6) Code optimization == 229 226 ??? 230 227 231 == ( X) Final steps ==228 == (6) Final steps == 232 229 '''Good practice''' 233 230 * no warning/error message should remain during compile (also try debug options) … … 236 233 * PRINT/WRITE statements for debugging 237 234 * Check that all parameters are used 235 236 237 238 ------------- 239 * place '''&''' character for line continuation at position 80 (minimum), max at position 120\\('''Note:''' FORTRAN-2003 defines a limit of 39 continuation lines)
