Changes between Version 23 and Version 24 of doc/tec/developerrules/palmstandard
- Timestamp:
- Jan 8, 2021 3:44:15 PM (4 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
doc/tec/developerrules/palmstandard
v23 v24 9 9 10 10 \\ 11 = (1) General hints & requirements = 12 == (1.1) Language == 13 * '''Fortran-2003''' standard (all Fortran compilers can handle this, Fortran-2008 standard not yet supported by all compilers) 11 = (1) General rules = 12 13 In all code files, independent of the programming language used: 14 14 15 * Use '''English''' language only 15 16 * Use '''ASCII''' characters only 16 * Use '''SI units''' as physical units 17 * Use '''SI units''' for physical quantities 18 * '''NO''' use of tab characters (only exception: Makefile), because depending on the text editor, the code indentations might be corrupted. 19 20 21 = (2) Python = 22 23 For Python code, we follow [https://www.python.org/dev/peps/pep-0008 PEP 8]. 24 25 26 = (3) Fortran = 27 28 == (3.1) General hints & requirements == 29 30 === (3.1.1) Language === 31 32 * '''Fortran-2003''' standard (all Fortran compilers can handle this, Fortran-2008 standard not yet supported by all compilers) 17 33 * Line-length limit 18 34 * '''100 characters (soft limit)''' for optimal readability 19 35 * '''132 characters (hard limit)''' absolute limit for most compilers! 20 * '''NO''' use of tab characters (only exception: Makefile), because depending on the text editor, the code indentations might be corrupted.21 22 36 || '''AVOID''' || '''USE INSTEAD''' || 23 37 || COMMON blocks || ... || … … 40 54 }}} 41 55 42 == (1.2) Implementing new features to PALM==56 === (3.1.2) Implementing new features to PALM === 43 57 (will follow) 44 58 * module structure (attach a template or link to template in repo) 45 59 * available interfaces in the PALM core 46 60 47 \\ 48 = (2) Coding=49 50 == (2.1) Code structure==61 62 == (3.2) Coding == 63 64 === (3.2.1) Code structure === 51 65 * One MODULE per file (only exception: modules.f90) 52 66 * Clarify program entities, i.e. use {{{SUBROUTINE <name> ... END SUBROUTINE <name>}}}, same holds for INTERFACE, MODULE, PROGRAM statements 53 67 54 == (2.2) Variable & parameter declarations==68 === (3.2.2) Variable & parameter declarations === 55 69 * Clear structure in declaration part, in this order: USE --> IMPLICIT NONE --> declarations --> SAVE --> PRIVATE --> PUBLIC list_of_public_variables 56 70 * '''IMPLICIT NONE''' | All subroutines and functions must include this statement, i.e all variables must be explicitly typed. It also allows the compiler to detect typographical errors in variable names. For MODULEs, one IMPLICIT NONE statement in the modules definition section is sufficient. … … 77 91 * '''INTERFACE blocks''' | Explicit interface blocks are required between routines if optional or keyword arguments are to be used. They also allow the compiler to check that the type, shape and number of arguments specified in the CALL are the same as those specified in the subprogram itself. Fortran 2003 compilers can automatically provide explicit INTERFACE blocks for routines contained in a MODULE. 78 92 79 == (2.3) Pre-processor directives==93 === (3.2.3) Pre-processor directives === 80 94 PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered by most Fortran compilers. The use of pre-processor directives inside the code allow to specifically exclude or include parts of the code for compilation. 81 95 Only few pre-processor directives are used in PALM ([wiki:doc/app/cpp_options list of directives]), and activated by the {{{%cpp_options}}} variable in the .palm.config.<configuration_identifier> file. … … 92 106 }}} 93 107 94 == (2.4) Allowed operators==108 === (3.2.4) Allowed operators === 95 109 * Use /=, <, <=, ==, >, >=, etc. as relational operators instead of .GE., .LT., etc. 96 110 * Use .AND., .OR., .NOT. as logical operators 97 111 98 == (2.5) Error messages==112 === (3.2.5) Error messages === 99 113 (will follow) 100 114 * Use message routine (explain parameters here...) 101 115 * I/O error conditions via IOSTAT (is this fail-safe for different compilers?) 102 116 103 == (2.6) Code optimization==117 === (3.2.6) Code optimization === 104 118 (will follow) 105 119 106 120 \\ 107 = (3) Documenting & commenting=121 == (3.3) Documenting & commenting == 108 122 {{{ 109 123 #!div style="align:'left'; width: 450px; border: 0px solid; float:right" … … 113 127 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. 114 128 115 == (3.1) External documentation==129 === (3.3.1) External documentation === 116 130 You are in the middle of it. We have an extensive online documentation wiki embedded into a [https://trac.edgewall.org/ trac] project management system, directly connected to the svn repository, allowing to [browser browse the PALM code] @ all its former and of course current revision in a web-based environment.\\\\ 117 131 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 [wiki:doc 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. 118 132 119 == (3.2) Internal documentation==133 === (3.3.2) Internal documentation === 120 134 '''File header section''' 121 135 (see Fig. 1) … … 176 190 177 191 \\ 178 = (4) Naming conventions=179 == (4.1) Use of lower & upper case letters==192 == (3.4) Naming conventions == 193 === (3.4.1) Use of lower & upper case letters === 180 194 * '''Upper case:''' Fortran keywords and intrinsic functions or routines, e.g. 181 195 * SUBROUTINE, MODULE, etc. … … 186 200 * '''Lower case:''' Everything else! 187 201 188 == (4.2) Names for routines and variables==202 === (3.4.2) Names for routines and variables === 189 203 Use clear, unambiguous naming in '''lower-case letters''', with individual words separated by underscore. 190 204 * MODULE/SUBROUTINE: name is constructed (if applicable) as verb followed by object, e.g.\\ … … 203 217 204 218 \\ 205 = (5) Formatting & sorting=219 == (3.5) Formatting & sorting == 206 220 [[NoteBox(warn, Line length limit: '''100''' characters ('''soft limit''')\, '''132''' characters ('''hard limit'''))]] 207 221 208 == (5.1) Indentation, spaces & line breaks==222 === (3.5.1) Indentation, spaces & line breaks === 209 223 '''__General module/subroutine structure''' 210 224 (see Fig. 2) … … 248 262 249 263 \\\\\\\\\\ 250 == (5.2) Alignment==264 === (3.5.2) Alignment === 251 265 (see Fig. 4) 252 266 {{{ … … 262 276 * Alignment of related code, e.g. in complex equations or setting of initial values for variables 263 277 264 == (5.3) Alphabetical sorting==278 === (3.5.3) Alphabetical sorting === 265 279 * Members in {{{ONLY}}} lists of USE statements (see e.g. Fig. 4) 266 280 * Parameters in Fortran {{{NAMELIST}}} lists (see e.g. initialization_parameters namelist in parin.f90) … … 268 282 * Variables in declaration statements (see Fig. 4) 269 283 270 == (5.4) Handling of lists of variables==284 === (3.5.4) Handling of lists of variables === 271 285 * In namelists, one variable per line: 272 286 {{{ … … 283 297 284 298 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 285 = (6) Final steps=286 == Good practice ===299 == (3.6) Final steps == 300 === Good practice === 287 301 * No warning/error message should remain during compile (also try debug options) 288 302 289 == Clean up==303 === Clean up === 290 304 * Remove PRINT/WRITE statements for used for debugging 291 305 * Check that all parameters are used
