We recognise that the beating heart of DSSAT is the community of scientists that work with the underlying science in the model.  These people are scientists who write Fortran code, and who, understandably, have very limited interest in, and willingness to adopt, changes to their programming workflows.

This document provides a bare minimum set of guidelines for new Fortran code that is developed in scientific modules in the DSSAT CSM.  These are not requirements, but can be viewed as set of humble requests.

Coding guidelines are as follows, ordered from most important to least important:

• Understandability and readability of code are more important than any other consideration. Use lots of comments to describe what you are doing. Use indentation in ‘do, ‘if, and ‘Select Case’ blocks.
• Variables should be defined in the code with units specified.
• Please use ‘implicit none’; this forces the declaration of variables, which is a Good Thing.
• Please use intent This greatly reduces the chances of unwanted ‘side effects’ that can be near-impossible to debug.
• Functions should have no side effects. Therefore, all function arguments should be intent(in).
• Please avoid the use of COMMON
• Please avoid GOTO and numeric labels.
• Please use ‘Javadoc’-style comments to define subroutine or function inputs, outputs and to describe the purpose of the code (see sample below).
• Please avoid dynamic memory and pointers, which make the code difficult to navigate.
• The VBranch variable in ModuleDefs should be used to “brand” simulation output files with the name of your GitHub branch.

Anatomy of a CSM module

Additional Fortran Style Suggestions

1. Use short names for variables whose use is clear, e.g., i and j are acceptable as array subscripts, and x and y are fine as function dummy arguments. Use longer names for entities whose purpose is not obvious, e.g., distance_to_the_moon.
2. Do not use the same name with different uppercase/lowercase spelling, e. g., N and n.
3. Use the letters O and l and the digits 0 and 1 in names only when it will be perfectly clear which character is meant.
4. Insert meaningful comments frequently.
5. Use blank lines to separate related parts of a program.
6. Indent blocks a consistent number of spaces (such as 2, 3, or 4).
7. Use white space freely in statements (e. g., around delimiters).
8. Do not use nonstandard or obsolescent features.
9. Do not write “tricky” code to save a few lines or a few milliseconds. If execution efficiency is important, write code that reflects the algorithm, instrument the code, try some variations, and comment liberally including the original code.