Code style guide

MOM6 code style guide

MOM6 makes use of Fortran2003 with some judicious use of Fortran2008 constructs, but it does not use any extensions beyond what is in those standards. To help keep the code readily understandable, this page makes recommendations about how to use or not use the various features of the modern Fortran language.

Code style is typically a personal choice, but when styles clash it can lead to discord. These standards have been adopted in an attempt to promote harmony and clarity.

White space

• No tabs
• No trailing white space
• Indents should be consistent (same amount used in contiguous blocks)
• Preferred indent is 2 spaces
  • "preferred" might understate the reaction invoked by other indent amounts! 😉
• Continuation lines should be indented at least 4 spaces, but more space can be used if it helps align lines
• No white space between a function name and the opening parenthesis
• White space after all language token
  • if(a==0) is legal fortran but bad style. Use if (a==0) instead.
  • if (a == 0) is even better, since == is a language token.
• Use space around the equal sign in variable assignment, but not when using a named optional argument
  • a = b is strongly preferred over a=b
    • One exception is loop indices, where do i=is,ie is acceptable
  • call fn(arg1, arg_name=a) is strongly preferred over call fn(arg1, arg_name = a)

Line length

Some compilers handle very long lines of code gracefully, but MOM6 needs to adhere to the Fortran standard, which is 132 characters for code, after any macro expansion. MOM6 does use macros for some memory declarations, so we need to build in some added space in setting MOM6 guidelines:

• The target maximum length for MOM6 code lines (exclusive of comments) is 100 characters
  • 80 character lines can be much easier to read if printed; smaller lines are encouraged where they make sense
• No lines of MOM6 code should exceed 120 characters, including comments

Local variables

• Local variable declarations appear after all the dummy argument declarations, and in the case of a function the return value. We often use ! Local variables to delineate between the argument and local variable declarations.
• Local variables should preferably be descriptive multi-character names meaningful in their context, e.g. del_rho_int (delta rho at interface).
• If using a highly abbreviated or short name, the declaration MUST be commented.
• Units should be provided in the comments describing real variables.
• Multi-word names should use snake_case (e.g. delta_rho).
  • snake_case admittedly used more characters than camelCase but unfortunately doxygen interprets the Fortran standard too literally and throws away any attempts to use CamelCase. We briefly adopted CamelCase for new code but are systematically replacing it as we doxygen-ize existing code.

Block constructs

• do and if constructs should be terminated with the combined enddo and endif statements, respectively.
• All other block end statements separate the end token (e.g. end program [label])
  • Examples: program, module, type, subroutine, function, interface, select

Loop indices

Soft case convention

• i,j,k are used for cell-center, layer-center references, e.g. h(i,j,k), T(i+1,j,k).
• I,J are used for staggered, cell-edge references, e.g. u(I,j,k), v(i,J,k), q(I,J,k), u(I-1,j,k). We use a north-east staggering convention so the I means i+1/2 and I-1 means i-1/2.
• K is used for the interface (between layer) references, e.g. del_t(i,j,K) = T(i,j,K+1) - T(i,j,K). The vertical staggering is such that interface K=1 is above layer k=1 so that K means k-1/2 and K+1 means k+1/2.

Global / module data

• Absolutely NO!
• There are a few exceptions which are strictly for debugging non-shared memory applications. Do not use these as an excuse for adding module data.

Module use statements

• Modules may use interfaces, data-types, and constant parameters from other modules via module use statements
  • Modules may not use variables from other modules via use statements
  • All MOM variables are passed around as explicit arguments in interfaces.
• All module use statements must include the , only modifier

Implicit variables

• Absolutely NO!
• All MOM6 modules must declare implicit none ; private
  • Top-level drivers (i.e., files declaring a program main()) only need implicit none

Array syntax

• We do not permit scalar-style expressions without the colon notation, e.g.
  • tv%S = 0. is forbidden.
• We do allow array syntax for whole array initialization, e.g.
  • tv%S(:,:,:) = 0.
• We do allow array syntax for identical copies, e.g.
  • S_tmp(:,:,:) = tv%S(:,:,:)
• We do not allow whole array-syntax for math expressions that include halos because halos are not guaranteed to have valid data:
  • tmp(:,:) = 1.0 / G%areaT(:,:) might have zeros in the halo region.
  • call post_data(id_AT, G%areaT(:,:)*tv%(T(:,:,1)) is wrong because it can use uninitialized data in halos.

Data flow

• All needed data is passed via arguments to subroutines and functions, or as the returned value of a function.
• All arguments must have declared intent, with the exception of pointers: i.e. intent(in), intent(out), intent(inout).
• Opaque types are preferred, i.e. referencing members of types defined in other modules is discouraged.

Documentation in code

• Do it when you are writing the code in the first place!
• All subroutines, functions, arguments, and elements of public types should be described in with dOxygen comments.
• All real variables should have a full physical description, including units.
• All comments should be clearly written and grammatically correct; American spelling is preferred.

Optimization for divides

Divisions are prone to NaNs and relatively expensive. An optimizing compiler will often rearrange math which makes debugging divisions by zero harder to catch.

• Many common reciprocals are pre-computed
  • Use Q(i,j) * G%IareaT(i,j) instead of Q(i,j) / G%areaT(i,j).
• Never write B / C * D which is ambiguous to humans (not the compiler)
  • Use ( B * D ) / C
• Never double divide: A / ( A + B / C)
  • Use ( A * C ) / ( A * C + B)

Arithmetic reproducibility

Floating point operations are sensitive to the order of operations (associativity), which can not generally be guaranteed due to compiler serialization and optimization.

Addition

Addition operations must be done in pairs. When more than one addition is required, the order should be specified using parentheses.

• This is bad:
  • z = a + b + c
• This is good:
  • z = (a + b) + c

Ideally, the order of operation should be chosen to give the best accuracy. For example, if a = 1. b = -1. and c = 1.e-20, then the order should be chosen to preserve the residual value.

• This is bad:
  • a + (b + c) == 0.
• This is good:
  • (a + b) + c == 1.e-20

Not only does this impact reproducibility, but the second choice is more accurate and avoids a potential division by zero.

All operations should be ordered, but no particular ordering is enforced. Contributors are encouraged to consider the most accurate order of operations. In some cases the order of sums can be chosen to give expressions that yield identical answers if the underlying horizontal coordinate is rotated by 90 or 180 degrees, which would define the preferred order of operations.

We avoid the Fortran sum() function since the result is dependent on the order of operations within the summation. Using explicit loops allows us to define the order of summation. So

a = sum(b(:))

should be

a = 0.
do k = 1, nz
  a = a + b(k)
enddo

Global summation

Floating point operations across MPI ranks are volatile, since the order can change depending on the state of the network. Functions such as MPI_Reduce will not generally be reproducible when used for floating point arithmetic.

When performing summations over MPI ranks, use the reproducing_sum function.

use MOM_coms, only: reproducing_sum
...
sum = reproducing_sum(array(:,:))

Multiplication

Multiplication is also non-associative and thus not reproducible, but the impact is typically small. Results may depend on the order of operations, most often in the least significant bit of the fractional component.

In single precision, if a = b = 1 + 2**-23 and c = 1.5, then the following calculations differ:

• (a*b)*c = 1.50000036
• a*(b*c) = 1.50000048

Parentheses in multiplication operations are currently not enforced, but contributors should consider using them when applicable.

Trascendental functions

Use of transcendental functions, such as trigonometric functions, non-integer powers, and logarithms, are often implementation-dependent and should be avoided when possible.