| | 27 | = (5) Coding = |
| | 28 | == (5.1) Variable & parameter declarations == |
| | 29 | * Clear structure in declaration part, in this order: USE --> IMPLICIT NONE --> declarations --> SAVE --> PRIVATE --> PUBLIC list_of_public_variables |
| | 30 | * '''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. |
| | 31 | * '''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. |
| | 32 | * '''DIMENSION statement''' | or attribute is required in declaration statements. |
| | 33 | * ''' :: 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. |
| | 34 | * '''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). |
| | 35 | * '''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: |
| | 36 | {{{ |
| | 37 | INTEGER(iwp) :: counter |
| | 38 | |
| | 39 | REAL(wp) :: vara |
| | 40 | }}} |
| | 41 | The working precisions are set in module file mod_kinds. The defaults are 8 Byte REAL (double precision) and 4 Byte INTEGER (single precision). Only set distinct precisions if they are absolutely required, e.g. for INTEGER counters which may become larger than 232-1 or for REAL quantities which are required in single precision: |
| | 42 | {{{ |
| | 43 | INTEGER(idp) :: particle_id !< particle counter |
| | 44 | |
| | 45 | REAL(sp), DIMENSION(:,:,:), ALLOCATABLE :: lpf !< array for NetCDF output |
| | 46 | }}} |
| | 47 | * '''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. |
| | 48 | * '''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. |
| | 49 | * '''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. |
| | 50 | * '''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. |
| | 51 | * '''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. |
| | 52 | |
| | 53 | == (5.2) Allowed operators == |
| | 54 | * Use /=, <, <=, ==, >, >=, etc. as relational operators instead of .GE., .LT., etc. |
| | 55 | * Use .AND., .OR., .NOT. as logical operators |
| | 56 | |
| | 57 | == (5.3) Preprocessor directives == |
| | 58 | PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered by most FORTRAN compilers. |
| | 59 | 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. |
| | 60 | |
| | 61 | In the code, use this syntax (starting at first character of a line): |
| | 62 | {{{#if defined(__parallel) |
| | 63 | some code |
| | 64 | #endif}}} |
| | 65 | together with the standard logical operators '''!''' (instead of .NOT.), '''||''' (instead of .OR.), '''&&''' (instead of .AND.), e.g. |
| | 66 | {{{#if ! defined(__parallel) && (__netcdf)}}} |
| | 67 | |
| | 68 | == (5.4) Code structure == |
| | 69 | '''(move somewhere else)''' |
| | 70 | * one module per file (only exception: modules.f90) |
| | 71 | * clarify program entities, i.e. use {{{SUBROUTINE <name> ... END SUBROUTINE <name>}}}, same holds for INTERFACE, MODULE, PROGRAM |
| | 72 | |
| | 73 | == (5.5) Error messages == |
| | 74 | * Use message routine (explain parameters here...) |
| | 75 | * I/O error conditions via IOSTAT (is this fail-safe for different compilers?) |
| | 76 | |
| | 77 | == (5.6) Code optimization == |
| | 78 | ??? |
| | 79 | |
| | 80 | \\ |
| 191 | | = (5) Coding = |
| 192 | | == (5.1) Variable & parameter declarations == |
| 193 | | * clear structure in declaration part (USE, IMPLICIT NONE, declarations, SAVE, PRIVATE, PUBLIC list_of_public_variables) |
| 194 | | * for long lists form groups |
| 195 | | * one declaration line per variable |
| 196 | | |
| 197 | | == (5.2) Allowed operators == |
| 198 | | * Use /=, <, <=, ==, >, >=, etc. as relational operators instead of .GE., .LT., etc. |
| 199 | | * Use .AND., .OR., .NOT. as logical operators |
| 200 | | |
| 201 | | == (5.3) Preprocessor directives == |
| 202 | | PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered my most FORTRAN compilers. |
| 203 | | Only few pre-processor directives are used in PALM, and activated by the {{{%cpp_options}}} variable in the .palm.config.<configuration_identifier> file. |
| 204 | | |
| 205 | | Table or link to other page |
| 206 | | || '''flag''' || '''description''' || |
| 207 | | || __parallel || .... || |
| 208 | | |
| 209 | | Use this syntax (starting at first character of a line): |
| 210 | | {{{#if defined(__parallel) |
| 211 | | some code |
| 212 | | #endif}}} |
| 213 | | together with the standard logical operators '''!''' (instead of .NOT.), '''||''' (instead of .OR.), '''&&''' (instead of .AND.), e.g. |
| 214 | | {{{#if ! defined(__parallel) && (__netcdf)}}} |
| 215 | | |
| 216 | | == (5.4) Code structure == |
| 217 | | '''(move somewhere else)''' |
| 218 | | * one module per file (only exception: modules.f90) |
| 219 | | * clarify program entities, i.e. use {{{SUBROUTINE <name> ... END SUBROUTINE <name>}}}, same holds for INTERFACE, MODULE, PROGRAM |
| 220 | | |
| 221 | | == (5.5) Error messages == |
| 222 | | * Use message routine (explain parameters here...) |
| 223 | | * I/O error conditions via IOSTAT (is this fail-safe for different compilers?) |
| 224 | | |
| 225 | | == (5.6) Code optimization == |
| 226 | | ??? |
| 227 | | |
