5.1 Style Guidelines

General Guidelines

• Fortran 90 Standard CSIM uses the F90 standard.

• Preprocessor The C preprocessor is required as the macro processor (cpp). All tokens should be uppercase to distinguish them from fortran code. The use of ifdef constructs should be avoided wherever possible. The option should be set in the namelist instead.

• Fixed-Form Source Fixed-form source will be used for readability. Columns 7 to 72 of a line may contain a Fortran statement, while columns 1 to 6 are reserved for special purposes. Blanks may be used freely anywhere. Exclamation marks should be used to denote comments. A statement may include a maximum of 19 continuation lines.

• Bounds Checking All code should be able to run when the following compiler options are set:
  • Array bounds checking
  • Automatic variables are initialized to NaN
  • Floating point exception conditions: overflow, division by zero, and invalid operations

Modules

• The use of modules is strongly encouraged since they provide global access to variables.
• Modules must have the same name as the file in which they reside, due to dependency rules used by "make" programs. This implies that multiple modules are not allowed in a single file.
• Module names must begin with "ice_". This will provide unique module names when CCSM is released as a single executable version.
• Related subroutines and variables should be placed in a single module/file rather than keeping a single routine per file.
• The use of common blocks is discouraged. Modules are a better way to provide access to declared entities via the "use" statement.
• If possible, access to variables should be limited through use of only and private clauses in the "use" statements.

Subroutines

• Inline any subroutine or function that is only called once, unless it contains a significant amount of physics.
• Minimize work arrays and other extraneous copies unless the array is used multiple times within the same subroutine. Globally accessible work arrays are available in ice_work.F.

Loops

• Loops should be structured with the do-enddo construct as opposed to numbered loops.
• Loops should be combined as much as possible for readability and performance.
• Subroutine calls within loops over horizontal indices i and j should be avoided to produce a more vector-friendly code.
• Short loops should be placed outside of longer loops to produce vector-friendly code. For example, loops over ice thickness categories should be placed outside of loops over horizontal indices i and j.

Array Syntax

• Whole array expressions are encouraged for performance reasons. For example,

                   do i = 1, imt
                     a(i) = b(i) + c(i)
                   enddo
  

  is more desirable than

                   a = b + c
  

Allocatable Arrays

• Allocatable arrays should be avoided for performance reasons.

Variable Names

• State Variables Primary state variables should use the following naming convention:
  • aicen(i,j,n) ice concentration for each ice category
  • aice(i,j) ice concentration aggregated over all ice categories
  • ain(n) ice concentration in a single column, for each ice category

  Variables that are not state variables but are used in a similar manner should also follow this naming convention. Note that ai is not a good choice for a variable name.

• Descriptive Names Variable names should be descriptive and long enough to be found, for example with the UNIX "grep" utility, without pages of extraneous material. For example, eice and esno are preferable to ei and es.

• Variables with Similar Names Variables with the same name, but with different numbers of arguments should not be used in different places. For example, an array Ts(i,j) in one subroutine should not be used as a local variable Ts in another. An exception to this would be the work arrays, which should always be local.

Variable Declarations

• Variables should be declared in F90 format, using a double colon.
• The F90 kind type should be used for all variable declarations.
• Continuation lines are encouraged for declarations of arrays that have similar kinds and dimensions. For example:

        real (kind=dbl_kind), dimension (imt_local,jmt_local) ::
       &   aice     ! concentration of ice
       &,  vice     ! volume per unit area of ice          (m)
       &,  vsno     ! volume per unit area of snow         (m)
  

• Variables should be declared one per line to allow a comment field after it, with a "!" character followed by the comment text.
• Variables of a similar type and function may be grouped together on a single line. For example:

       integer (kind=int_kind) :: nyrp,mdayp,weekp       ! previous year, day, week
  

Code indentation

• Code within loops and if blocks will be indented three characters.
• Continuation lines of an assignment statement should begin to the right of the assignment operator. For example,

     Fresh(i,j) = Fresh(i,j) + (vsn(nc)*Rside*rhos
    $                        +  vin(nc)*Rside*rhoi)/dt
  

• Continuation lines of a subroutine call should begin to the right of the "(" character. For example,

     call comp_matrices  ( rowflg, hin, Hmean,
    $                      Gamm, HGamm, H2Gamm )
  

Commenting of code

• Comments enclosed in horizontal lines are "major":

    !-----------------------------------------------------------------
    ! initializations
    !-----------------------------------------------------------------
  

  while those indented to match the following pertinent code are "minor":

    ! compute aggregate ice state and open water area
    call aggregate
  

• Short comments can be included on the same line as the source code preceded by the "!" character.
• Comments on adjacent lines should be aligned, if possible.

Portability

• The code will run on all platforms supported by CCSM. See the CCSM User's Guide for the most recent list of supported machines and platforms.
• Code should be developed using standard MPI (Message Passing Interface).
• The code should run efficiently on cache-based and vector machines.
• Standard F90 and MPI should be used so that the code is easily portable to other platforms.

Incomplete and dead code

• Incomplete code should be indicated by comments that include "TBD".
• Variables that are declared but not used should be removed.
• Code that is commented out should either be removed or contain comments as to why it is still there.

Miscellaneous

• Tabs should not be used for spacing; they create a large inconvenience when editing.
• Code will be written in lower case. This differentiates Fortran code from C preprocessor tokens, since the convention has been established that these are upper case.
• Use of the relational operators $<$, $>$, $<$=, $>$=, ==, and /= are preferred to .lt., .gt., .le., .eq., and .ne. for purposes of readability.
• The stop command should be avoided when exiting the code after an error. Instead, the subroutine abort_ice should be called.