GSI Coding Standards
This page provides a minimal set of standards
(requirements) placed on all code found within the GSI. Since this list was put together well after
GSI code development began, not all GSI code satisfies the below requirements. Existing GSI routines will be brought into
compliance over time. Modifications to
existing or the addition of new code will be required to satisfy the below
requirements. GSI coding standards are
expected to evolve over time and so users are encouraged to check back
frequently. Users may also submit their
coding standard suggestions to us.
To return to the main GSI code page, click here.
Page last modified: 11/1/2006 6:37 AM
GSI Coding Do’s
o
Constants
-
Use
globally defined constants from the constants module (constants.f90), not local
(routine specific) definitions.
-
Explicitly
specify precision of local numeric constants (e.g., use 10.0_r_kind instead of
10.0)
o
Declarations
-
All
routines must include “implicit none”
-
All
module declarations must explicitly specify which module components (variables
or routines) are used within the given routine (e.g., use constants, only: zero, one, two)
-
All
integer and real variables must be typed using type definitions in the kinds
module (kinds.f90)
-
The
INTENT attribute must be specified for all arguments passed into and out of
procedures (subroutines and functions)
o
Documentation
-
Document
all changes, not only around modified code but also in the documentation block
(doc block) at the head of each GSI subroutine or function. Look at subroutine gsisub.f90, glbsoi.f90,
and setuprhsall.f90 as examples.
-
When
modifying a routine, remember to add a one-line entry with change date,
programmer, and brief description. This
one-line entry goes in the program history log of the doc block.
-
Ensure
input/output argument documentation in doc block is consistent with
additions/deletions from calling list
o
Free
format code
-
Maintain
consistent and appropriate indenting of code.
-
Do
not use all uppercase or mixed upper/lower case for code or comments. All uppercase may be used for comments when
the intent is to draw the attention of readers to critical information
regarding the code block in question.
o
Modules
-
Use
modules to group related routines that use common module variables. There’s a growing tendency to place
everything in modules. This is not the
intended use of modules.
-
Add
private and public declarations to module contents. While this is currently done in only a small
number of GSI routines, it is a good coding practice and should be included in
future updates to GSI code (modifying existing routines or adding new
routines).
o
Tangent
linear and adjoint code
-
The
only acceptable identifiers for tangent linear and adjoint routine and / or
variable names are the suffixes “_tl” and “_ad”, respectively. Other naming conventions will not be
accepted.
GSI Coding Don’ts
o
Do
not neglect, ignore, or violate the above “do’s”
o
Do
not use, if at all possible, machine (compiler) specific functions or
calls. Doing so limits portability of
the code.
o
Do
not leave in code that was used for debugging purposes once the debugging is
complete
o
Do
not label user changes with comments that include the user’s name or
initials. For example, do not include a
comment like this: “!RT
change below” .