Changes between Version 17 and Version 18 of doc/tec/developerrules/palmstandard
- Timestamp:
- Nov 21, 2018 1:26:55 PM (6 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
doc/tec/developerrules/palmstandard
v17 v18 6 6 \\\\ 7 7 Formulated rules are based on the specifications given for the ocean dynamics model [https://www.nemo-ocean.eu/ NEMO]. 8 Other work that influenced the development of this standard are [http://www.cesm.ucar.edu/models/ccsm4.0/ Community Climate System Model] [http://www.cesm.ucar.edu//working_groups/Software/dev_guide/dev_guide/ Software Developer's Guide], and [attachment:european_standards-1.pdf European Standards For Writing and Documenting Exchangeable F ORTRAN90 Code].8 Other work that influenced the development of this standard are [http://www.cesm.ucar.edu/models/ccsm4.0/ Community Climate System Model] [http://www.cesm.ucar.edu//working_groups/Software/dev_guide/dev_guide/ Software Developer's Guide], and [attachment:european_standards-1.pdf European Standards For Writing and Documenting Exchangeable Fortran 90 Code]. 9 9 10 10 \\ 11 11 = (1) General hints & requirements = 12 12 == (1.1) Language == 13 * '''F ORTRAN-2003''' standard (all FORTRAN compilers can handle this, FORTRAN-2008 standard not yet supported by all compilers)13 * '''Fortran-2003''' standard (all Fortran compilers can handle this, Fortran-2008 standard not yet supported by all compilers) 14 14 * Use '''English''' language only 15 15 * Use '''ASCII''' characters only … … 55 55 * '''PARAMETER declaration''' | Variables used as constants should be declared with attribute PARAMETER and used always without copying to local variables. This prevents from using different values for the same constant or changing them accidentally. 56 56 * '''DIMENSION statement''' | or attribute is required in declaration statements. 57 * ''' :: notation''' | is quite useful to show that this program unit declaration part is written in standard F ORTRANsyntax, even if there are no attributes to clarify the declaration section. Always use the notation <blank>::<two blanks> to improve readability.57 * ''' :: notation''' | is quite useful to show that this program unit declaration part is written in standard Fortran syntax, even if there are no attributes to clarify the declaration section. Always use the notation <blank>::<two blanks> to improve readability. 58 58 * '''LEN specifier''' | Declare the length of a character variable using the CHARACTER (LEN=xxx) syntax - the LEN specifier is important because it is possible to have several kinds for characters (e.g. Unicode using two bytes per character, or there might be a different kind for Japanese e.g. NEC). 59 59 * '''Precision''' | Parameters and variables should not rely on vendor-supplied flags to supply a default floating point precision or integer size. The F2003 KIND feature should be used instead. Always use the default REAL- (wp) and INTEGER- (iwp) working precision in the respective declaration statements: … … 69 69 REAL(sp), DIMENSION(:,:,:), ALLOCATABLE :: lpf !< array for NetCDF output 70 70 }}} 71 * '''INTENT clause''' | All dummy arguments must include the INTENT clause in their declaration. This is extremely valuable to someone reading the code, and can be checked by compilers. A common mistake is to put the wrong type of variable in a routine call. So, develop the habit of checking types of arguments in parameter lists. Many modern compilers, especially for F ORTRAN 2003, check for consistent use within a file or across files using inter-procedural analysis. Compilers for FORTRAN2003 will also flag up errors at link time if there are explicit or implicit interfaces.71 * '''INTENT clause''' | All dummy arguments must include the INTENT clause in their declaration. This is extremely valuable to someone reading the code, and can be checked by compilers. A common mistake is to put the wrong type of variable in a routine call. So, develop the habit of checking types of arguments in parameter lists. Many modern compilers, especially for Fortran 2003, check for consistent use within a file or across files using inter-procedural analysis. Compilers for Fortran 2003 will also flag up errors at link time if there are explicit or implicit interfaces. 72 72 * '''PRIVATE attribute''' | Modules variables and routines should be encapsulated by using the PRIVATE attribute. What shall be used outside the module can be declared PUBLIC instead. Use USE with the ONLY attribute to specify which of the variables, type definitions etc. defined in a module are to be made available to the using routine. Of course you do not need to add the ONLY attribute if you include all or nearly all public declarations of a module. 73 73 * '''Data initialization''' | Improper data initialization is another common source of errors. A variable could contain an initial value you did not expect. This can happen for several reasons, e.g. the variable has never been assigned a value, its value is outdated, memory has been allocated for a pointer but you have forgotten to initialize the variable pointed to. Some compilers initialize variables to zero but when you port your code to another computer that does not do this previously working code will no longer work this can take some time to diagnose and longer to resolve. To avoid such mishaps, '''initialize''' variables as close as possible to where they are first used. If possible, give a default initial value in the declaration statement. 74 * '''Constants and magic numbers''' | Magic numbers should be avoided. Physical constants (e.g. pi, gas constants) must never be hardwired into the executable portion of a code. Instead, a mnemonically named variable or parameter should be set to the appropriate value, probably in the setup routine for the package. We realize that many parametrizations rely on empirically derived constants or fudge factors, which are not easy to name. In these cases it is not forbidden to leave such factors coded as magic numbers buried in executable code, but comments should be included referring to the source of the empirical formula. Hard-coded numbers should never be passed through argument lists. One good reason for this rule is that a compiler flag, which defines a default precision for constants, cannot be guaranteed. F ORTRAN2003 allows specification of the precision of constants through the "_" compile-time operator (e.g. 3.14_dp or 365_i8). So if you insist on passing a constant through an argument list, you must also include a precision specification in the calling routine. If this is not done, a called routine that declares the resulting dummy argument as, say, real(dp) or 8 bytes, will produce erroneous results if the default floating point precision is 4 byte.75 * '''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. F ORTRAN2003 compilers can automatically provide explicit INTERFACE blocks for routines contained in a MODULE.74 * '''Constants and magic numbers''' | Magic numbers should be avoided. Physical constants (e.g. pi, gas constants) must never be hardwired into the executable portion of a code. Instead, a mnemonically named variable or parameter should be set to the appropriate value, probably in the setup routine for the package. We realize that many parametrizations rely on empirically derived constants or fudge factors, which are not easy to name. In these cases it is not forbidden to leave such factors coded as magic numbers buried in executable code, but comments should be included referring to the source of the empirical formula. Hard-coded numbers should never be passed through argument lists. One good reason for this rule is that a compiler flag, which defines a default precision for constants, cannot be guaranteed. Fortran 2003 allows specification of the precision of constants through the "_" compile-time operator (e.g. 3.14_dp or 365_i8). So if you insist on passing a constant through an argument list, you must also include a precision specification in the calling routine. If this is not done, a called routine that declares the resulting dummy argument as, say, real(dp) or 8 bytes, will produce erroneous results if the default floating point precision is 4 byte. 75 * '''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. 76 76 77 77 == (2.3) Pre-processor directives == 78 PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered by most F ORTRANcompilers. The use of pre-processor directives inside the code allow to specifically exclude or include parts of the code for compilation.78 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. 79 79 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. 80 80 … … 118 118 '''File header section''' 119 119 (see Fig. 1) 120 a. Doxygen command for F ORTRANfile name ('''!>''' starts a doxygen command line)120 a. Doxygen command for Fortran file name ('''!>''' starts a doxygen command line) 121 121 b. PALM license section (you may have to add other licenses if allowedly implementing code from other models) 122 122 c. Revision comments (see [wiki:doc/tec/developerrules/svnbranch working with svn branches] and [wiki:doc/tec/developerrules committing to trunk]) … … 176 176 = (4) Naming conventions = 177 177 == (4.1) Use of lower & upper case letters == 178 * '''Upper case:''' F ORTRANkeywords and intrinsic functions or routines, e.g.178 * '''Upper case:''' Fortran keywords and intrinsic functions or routines, e.g. 179 179 * SUBROUTINE, MODULE, etc. 180 180 * INTEGER, REAL, PARAMETER, etc. … … 260 260 == (5.3) Alphabetical sorting == 261 261 * Members in {{{ONLY}}} lists of USE statements (see e.g. Fig. 4) 262 * Parameters in {{{NAMELISTS}}} (see e.g. initialization_parameters NAMELISTin parin.f90)262 * Parameters in Fortran {{{NAMELIST}}} lists (see e.g. initialization_parameters namelist in parin.f90) 263 263 * Declaration types (first {{{CHARACTER}}}, then {{{INTEGER}}}, etc., see Fig. 4) 264 264 * Variables in declaration statements (see Fig. 4)
