| | 22 | {{{#!comment |
| | 23 | Examples for Fortran 95 are: |
| | 24 | ◦ COMMON blocks - use the declaration part of MODULEs instead. |
| | 25 | ◦ EQUIVALENCE - use POINTERs or derived data types instead to form data structures. Please try to avoid this anyway as it is usually a source of bugs. |
| | 26 | ◦ Assigned and computed GOTOs - use the CASE construct instead. |
| | 27 | ◦ Arithmetic IF statements - use the block IF, ELSE, ELSEIF, ENDIF or SELECT CASE construct instead. |
| | 28 | ◦ Labeled DO constructs - use unlabeled ENDDO instead. Nevertheless non-number label can be used for big iterative loop of recurcive algorithm. |
| | 29 | ◦ I/O routines END and ERR - use IOSTAT instead (the use is somehow restricted due to compiler implementation dependent error numbering). (This is not yet done throughout the PALM code action!) |
| | 30 | ◦ FORMAT statements: use character parameters or explicit format- specifiers inside the READ or WRITE statement instead. (This is not yet done throughout the PALM code action!) |
| | 31 | ◦ GOTO and CONTINUE statement - use IF, CASE, DO WHILE, EXIT or CYCLE statements or a contained SUBROUTINE instead. If you feel you cannot avoid a GOTO and or CONTINUE statement, then add a clear comment to explain what is going on and why you need to use GOTO. |
| | 32 | ◦ PAUSE – just never use it. |
| | 33 | ◦ ENTRY statements: a subprogram must only have one entry point. |
| | 34 | ◦ RETURN – it is obsolete and so not necessary at the end of program units. |
| | 35 | ◦ Fixed source form – use free form instead. |
| | 36 | ◦ Avoid functions with side effects. There are good reasons to avoid this. First, the code is easier to understand, if you can rely on the rule that functions don't change their arguments, second, some compilers generate more efficient code for PURE (in Fortran 2003 there are the attributes PURE and ELEMENTAL) functions, because they can store the arguments in different places. This is especially important on massive parallel and on vector machines as well. |
| | 37 | ◦ DATA and BLOCK DATA - initialisers in Fortran 2003 give this functionality. |
| | 38 | }}} |
| 49 | 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. |
| 50 | 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. |
| 51 | 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. |
| 52 | 76 | |
| 53 | | == (5.2) Allowed operators == |
| | 77 | == (2.3) Pre-processor directives == |
| | 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 | 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 | |
| | 81 | In the code, use this syntax (starting at first character of a line):\\ |
| | 82 | {{{ |
| | 83 | #if defined(__parallel) |
| | 84 | some code |
| | 85 | #endif |
| | 86 | }}} |
| | 87 | together with the standard logical operators {{{!}}} (instead of .NOT.), {{{||}}} (instead of .OR.), {{{&&}}} (instead of .AND.), e.g. |
| | 88 | {{{ |
| | 89 | #if ! defined(__parallel) && (__netcdf) |
| | 90 | }}} |
| | 91 | |
| | 92 | == (2.4) Allowed operators == |
| 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 == |
| | 96 | == (2.5) Error messages == |
| | 97 | (will follow) |
| 77 | | == (5.6) Code optimization == |
| 78 | | ??? |
| 79 | | |
| 80 | | \\ |
| 81 | | = (2) Documenting & commenting = |
| 82 | | {{{ |
| 83 | | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| 84 | | [[Image(rules_header.png, 450px, right, margin-right=2, margin-top=0, border=0)]]\\ |
| 85 | | '''Fig. 4''' PALM source-code header example. Click to enlarge. |
| | 101 | == (2.6) Code optimization == |
| | 102 | (will follow) |
| | 103 | |
| | 104 | \\ |
| | 105 | = (3) Documenting & commenting = |
| | 106 | {{{ |
| | 107 | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| | 108 | [[Image(rules_header.png, 450px, right, margin-right=2, margin-top=0, border=2)]]\\ |
| | 109 | '''Fig. 1''' PALM source-code header example. Click to enlarge. |
| 185 | | (see Fig. 1) |
| 186 | | {{{ |
| 187 | | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| 188 | | [[Image(rules_indent_general.png, 450px, right, margin-right=2, margin-top=0, border=0)]]\\ |
| 189 | | '''Fig. 1''' Indentation example with highlighted whitespaces. Click to enlarge. |
| | 209 | (see Fig. 2) |
| | 210 | {{{ |
| | 211 | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| | 212 | [[Image(rules_indent_general.png, 450px, right, margin-right=2, margin-top=0, border=2)]]\\ |
| | 213 | '''Fig. 2''' Indentation example with highlighted whitespaces. Click to enlarge. |
| 209 | | (see Fig. 2) |
| 210 | | {{{ |
| 211 | | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| 212 | | [[Image(rules_indent_loops.png, 450px, right, margin-right=2, margin-top=0, border=0)]]\\ |
| 213 | | '''Fig. 2''' Indentation & whitespaces in loops. Click to enlarge. |
| | 233 | (see Fig. 3) |
| | 234 | {{{ |
| | 235 | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| | 236 | [[Image(rules_indent_loops.png, 450px, right, margin-right=2, margin-top=0, border=2)]]\\ |
| | 237 | '''Fig. 3''' Indentation & whitespaces in loops. Click to enlarge. |
| 223 | | == (4.2) Alignment == |
| 224 | | (see Fig. 3) |
| 225 | | {{{ |
| 226 | | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| 227 | | [[Image(rules_align.png, 450px, right, margin-right=2, margin-top=0, border=0)]]\\ |
| 228 | | '''Fig. 3''' Alignment example. Click to enlarge. |
| | 247 | == (5.2) Alignment == |
| | 248 | (see Fig. 4) |
| | 249 | {{{ |
| | 250 | #!div style="align:'left'; width: 450px; border: 0px solid; float:right" |
| | 251 | [[Image(rules_align.png, 450px, right, margin-right=2, margin-top=0, border=2)]]\\ |
| | 252 | '''Fig. 4''' Alignment example. Click to enlarge. |
