| 11 | | * FORTRAN-2003 standard (all FORTRAN compilers can handle this, FORTRAN-2008 standard not yet supported by all compilers) |
| 12 | | * Use English language only |
| 13 | | * Use ASCII characters only |
| 14 | | * Use SI units as physical units |
| 15 | | * '''NO''' use of tab characters\\(only exception: Makefile) |
| | 11 | * '''FORTRAN-2003''' standard (all FORTRAN compilers can handle this, FORTRAN-2008 standard not yet supported by all compilers) |
| | 12 | * Use '''English''' language only |
| | 13 | * Use '''ASCII''' characters only |
| | 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 |
| | 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 !> |
| | 35 | |
| | 36 | == (2.2) Internal documentation == |
| | 37 | (one variable per declaration statement!)\\\\ |
| | 38 | '''Description of variables''' |
| | 39 | * Short description for each declared variable, comments should be aligned per declaration block\\ |
| | 40 | {{{ |
| | 41 | LOGICAL :: conserve_water_content = .TRUE. !< open or closed bottom surface for the soil model |
| | 42 | LOGICAL :: constant_roughness = .FALSE. !< use fixed/dynamic roughness lengths for water surfaces |
| | 43 | |
| | 44 | REAL(wp) :: c_surface = 20000.0_wp !< Surface (skin) heat capacity (J m-2 K-1) |
| | 45 | REAL(wp) :: deep_soil_temperature = 9999999.9_wp !< Deep soil temperature (K) |
| | 46 | }}} |
| | 47 | * If comment reaches over 120 characters (hard line limit), break comment into (max.) 2 lines |
| | 48 | {{{ |
| | 49 | LOGICAL :: conserve_water_content = .TRUE. !< open or closed bottom surface for the soil model |
| | 50 | !< in the land-surface model |
| | 51 | }}} |
| | 52 | |
| | 53 | '''Commenting of code blocks'''\\ |
| | 54 | * Carefully comment each block of code |
| | 55 | * Comments '''always''' start with |
| | 56 | {{{ |
| | 57 | ! |
| | 58 | !-- |
| | 59 | }}} |
| | 60 | * Comment text always starts at same position as indented code to be described, and break text into several lines if '''> 80 characters''' are reached |
| | 61 | {{{ |
| | 62 | DO j = nys, nyn |
| | 63 | ! |
| | 64 | !-- Tendency terms for u-velocity component. Please note, in case of |
| | 65 | !-- non-cyclic boundary conditions the grid point i=0 is excluded from |
| | 66 | !-- the prognostic equations for the u-component. |
| | 67 | IF ( i >= nxlu ) THEN |
| | 68 | |
| | 69 | tend(:,j,i) = 0.0_wp |
| | 70 | IF ( timestep_scheme(1:5) == 'runge' ) THEN |
| | 71 | }}} |
| | 72 | * Avoid superfluous comments like |
| | 73 | {{{ |
| | 74 | ! |
| | 75 | !-- Loop over all grid indices |
| | 76 | DO i = nxl, nxr |
| | 77 | DO j = nys, nyn |
| | 78 | }}} |
| | 79 | |
| | 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. |
| | 83 | |
| | 95 | |
| | 96 | == (3.2) Names for routines and variables == |
| | 97 | Use clear, unambiguous naming in '''lower-case letters''', with individual words separated by underscore. |
| | 98 | * MODULE/SUBROUTINE: name is constructed (if applicable) as verb followed by object, e.g.\\ |
| | 99 | {{{land_surface_model}}} or {{{read_restart_data}}} |
| | 100 | * MODULE/SUBROUTINE files: <filename>.f90 --> MODULE <filename> ... END MODULE <filename> (simplification of Make process) |
| | 101 | * Functions: names provide information about the value it is expected to return, e.g.\\ |
| | 102 | {{{solar_zenith_angle( )}}} |
| | 103 | * Variables & constants: names are readable, memorable and descriptive |
| | 104 | * LOGICAL (boolean) variables: give names that imply\\ |
| | 105 | {{{TRUE}}} or {{{FALSE}}} |
| | 106 | |
| | 107 | '''PROHIBITED:''' |
| | 108 | * Names that may clash with the operating system or language intrinsic, e.g.\\ |
| | 109 | {{{read( )}}} or {{{access( )}}} |
| | 110 | * 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)) |
| 106 | | == Commenting & documentation == |
| 107 | | 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 Doxygen, a tool for generating documentation and flow charts from annotated source code. This requires some special formatting, as described below. |
| 108 | | |
| 109 | | '''File header section''' |
| 110 | | * todos, notes, author,.... |
| 111 | | * Declaration !< Description |
| 112 | | * see file header |
| 113 | | * @author etc. |
| 114 | | * MODULE/SUBROUTINE description !> |
| 115 | | |
| 116 | | '''Inside the code''' |
| 117 | | * Examples.png.. |
| 118 | | * Avoid superfluous comments, such as\\ {{{a = a + 1 ! Increment a by one}}} |
| 119 | | * Example for multiple-line declaration comment |
| 120 | | ! |
| 121 | | !-- Text starts at same position as indented code to be described |
| 122 | | |
| 123 | | '''Outside the code''' |
| 124 | | 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 [browse the PALM code] @ all its former and of course current revision in a web-based environment. |
| 125 | | 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. |
| 133 | | == Naming conventions == |
| 134 | | Use clear, unambiguous naming in '''lower-case letters''', with individual words separated by underscore. |
| 135 | | * MODULE/SUBROUTINE: name is constructed (if applicable) as verb followed by object, e.g.\\ |
| 136 | | {{{land_surface_model}}} or {{{read_restart_data}}} |
| 137 | | * MODULE/SUBROUTINE files: <filename>.f90 --> MODULE <filename> ... END MODULE <filename> (simplification of Make process) |
| 138 | | * Functions: names provide information about the value it is expected to return, e.g.\\ |
| 139 | | {{{solar_zenith_angle( )}}} |
| 140 | | * Variables & constants: names are readable, memorable and descriptive |
| 141 | | * LOGICAL (boolean) variables: give names that imply\\ |
| 142 | | {{{TRUE}}} or {{{FALSE}}} |
| 143 | | |
| 144 | | '''PROHIBITED:''' |
| 145 | | * Names that may clash with the operating system or language intrinsics, e.g.\\ |
| 146 | | {{{read( )}}} or {{{access( )}}} |
| 147 | | * 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)) |
| | 187 | |
