PALM coding rules

Why to follow some standards?

Because everyone has her/his own programming style, sort of a dialect, making it difficult for other developers to understand, extend, debug, or optimize the code. So what do we do? We learn and apply the coding standard to make PALM more easily readable for all current and future developers. Let's all work on that together. We are aware that the PALM core doesn't completely comply with the following rules yet, but we are working on that.

Formulated rules and specifications are based on the specifications given for the ocean dynamics model [add-new-link-to NEMO]. Other work that influenced the development of this standard are [add-link Community Climate System Model], [add-link Software Developer's Guide], [add-link Report on Column Physics Standards], and [add-link European Standards For Writing and Documenting Exchangeable FORTRAN 90 Code].

(1) General hints & requirements

(1.1) Language

• FORTRAN-2003 standard (all FORTRAN compilers can handle this, FORTRAN-2008 standard not yet supported by all compilers)
• Use English language only
• Use ASCII characters only
• Use SI units as physical units

AVOID	USE INSTEAD
COMMON blocks	...

(1.2) Implementing new features to PALM

• module structure (template)
• available interfaces in the PALM core

(2) Documenting & commenting

(3) Naming conventions

(4) Formatting & sorting

Line length limit: 80 characters (soft) | 120 characters (hard). The absolute limit for compilers is 132 characters!

(4.1) Indenting, spaces & line breaks

General module/subroutine structure (see Fig. 1)

Fig. 1 Indention example with highlighted whitespaces. Click to enlarge.

• 0 whitespace in front of pre-processor directives
• 1 whitespace before MODULE, CONTAINS, SUBROUTINE (= first indention level)
• +3 whitespaces for all following indention levels
  (only exception: ONLY list in USE statements +4 whitespaces)
  
  
• 1 whitespace between individual strings, and between strings and symbols/numbers
• 1 whitespace after ,
  (only exception: 0 whitespace between array dimensions)
• 1 whitespace before ::
  (at minimum, see Sect. Alignment)
• 2 whitespace after : and ::
  
  
• 1 blank line between enclosed/unrelated blocks of instructions, assignments, clauses, statements, etc.
• 2 blank lines in front of each SUBROUTINE within a MODULE
• & character for line continuation at position 80 (minimum), max at position 120

Whitespaces between brackets (see Fig. 1)

• 0 whitespace between string and (
• 1 whitespace after ( and before )
  (only exception: 0 whitespace in dimensions)

Whitespaces in DO, IF blocks (see Fig. 2)

Fig. 2 Indention & whitespaces in loops. Click to enlarge.

• In general: 1 whitespace everywhere and 3 whitespace for each indention level
• But: 2 whitespace
  
  • between DO and loop index
  • after IF ( ) --> see CALL, THEN
  • in front of and after logical or relational operators (e.g. .OR., see list of allowed operators)

(4.2) Alignment

(see Fig. 3)

Fig. 3 Alignment example. Click to enlarge.

• Block-wise alignment of continuation line marker &
• Alignment of ONLY lists
• At least block-wise alignment for same type/group of declaration statement
• Alignment of message_string values
• Alignment of expressions between brackets (e.g. in IF ( ) THEN or in argument list of subroutine calls)
• Alignment of same level of mathematical expressions or array indices (missing in png)

(4.3) Alphabetical sorting

except for CALLs to modules/subroutines

Lower/upper case

Commenting & documentation

Documentation consists of putting information both inside and outside the source code. Comments should give a good idea of what the code does and where to look for any special activity.

Doxygen format

• Declaration !< Description
• see file header
• @author etc.
• MODULE/SUBROUTINE description !>

Header section

• todos, notes, author,....

Inside the code

• Examples.png..
• Avoid superfluous comments, such as
  a = a + 1 ! Increment a by one
• Example for multiple-line declaration comment

! !-- Text starts at same position as indented code to be described

Outside the code

(X) Coding

(X.1) Variable & parameter declarations

• clear structure in declaration part (USE, IMPLICIT NONE, declarations, SAVE, PRIVATE, PUBLIC list_of_public_variables)
• for long lists form groups
• one declaration line per variable

Naming conventions

Use clear, unambiguous naming in lower-case letters, with individual words separated by underscore.

• MODULE/SUBROUTINE: name is constructed (if applicable) as verb followed by object, e.g.
  land_surface_model or read_restart_data
• MODULE/SUBROUTINE files: <filename>.f90 --> MODULE <filename> ... END MODULE <filename> (simplification of Make process)
• Functions: names provide information about the value it is expected to return, e.g.
  solar_zenith_angle( )
• Variables & constants: names are readable, memorable and descriptive
• LOGICAL (boolean) variables: give names that imply
  TRUE or FALSE

PROHIBITED:

• Names that may clash with the operating system or language intrinsics, e.g.
  

read( ) or access( )

• 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))

Allowed operators

• Use /=, <, <=, ==, >, >=, etc. as relational operators instead of .GE., .LT., etc.
• Use .AND., .OR., .NOT. as logical operators

Preprocessor directives

PALM works with the C Pre-Processor (CPP), available on any UNIX platform, and covered my most FORTRAN compilers. Only few pre-processor directives are used in PALM, and activated by the %cpp_options variable in the .palm.config.<configuration_identifier> file.

Table or link to other page

flag	description
parallel	....

Use this syntax (starting at first character of a line): {{{#if defined(parallel)

some code

#endif}}}

together with the standard logical operators ''' (instead of .NOT.),

(instead of .OR.), && (instead of .AND.), e.g.

#if ! defined(__parallel) && (__netcdf)

File header

• Files always start with a doxygen-readable comment line including the FORTRAN file name.
• This is followed by the license section. If your code originates from another model, please clarify the license and permissions for this code to enter the PALM model system. It might be necessary in that case to add some more information to this header.
• The revisions section will later include short notes of the changes applied to a specific svn revision of this file. The $Id$ string is required so that svn knows to generate the respective time stamp for a revision (see existing SOURCE files).
• Finally, involved authors are included, followed by a description of the purpose and functions of the module. If necessary, TODOs, notes and known bugs can be added. The "!>" indicate doxygen-readable comment lines, the "@" marks doxygen variables.

(X) Code structure

• one module per file (only exception: modules.f90)
• clarify program entities, i.e. use SUBROUTINE <name> ... END SUBROUTINE <name>, same holds for INTERFACE, MODULE, PROGRAM

---

Error messages

• Use message routine (explain parameters here...)
• I/O error conditions via IOSTAT (is this fail-safe for different compilers?)

(X) Final steps

Good practice

• no warning/error message should remain during compile (also try debug options)

Clean up

• PRINT/WRITE statements for debugging
• Check that all parameters are used