----------- Coding Standards for GEMDM ----------
The present set of rules for F77 and F90 code is meant to ensure
a certain degree of uniformity and readability throughout the whole
library. It is also meant to ensure a minimum of documentation
especially for subroutine's interface.
WE PROMOTE: (not mandatory but highly recommended)
1) the use of 72 columns in .ftn and .cdk files; a greater number
of columns is also acceptable but should be kept below 100.
2) only one subroutine / function per .ftn file
3) full indentation of the Fortran code
4) NO code instructions in .cdk files, only variable declarations
MANDATORY:
---------------------------
Variables Naming Convention
---------------------------
Variable names have the generic form:
prefixes_name_postfixes
prefixes_name
name_postfixes
name
postfixes:
* real no postfix
* real*8 _8
* integer no postfix
* logical _L
* character _S
prefixes:
* Formal parameters (arguments of subroutine/function) F_
* Common block variables deckname_
where deckname is the name of the common deck file
containing the common definition
* Exception:
G_ and l_ prefixes used by variables from comdeck
glb_ld.cdk containing model topology information:
G_ used for Global information
l_ used for local information
* No prefixes for local variables
1) Postfixes are Mandatory
2) When a common variable contains information identical on all
processors, it is MANDATORY that the first character of the
prefixes be UPPERCASE
3) Constant names (parameter statements) must be all UPPERCASE
Note: The naming convention stated above forbids the use
of comdecks called "G.cdk", "l.cdk" or "F.cdk".
VMM: exception -- see comdecks vt*.cdk, nest.cdk, rhsc.cdk,
orh.cdk, p_geof.cdk
---------------
Comdecks format
---------------
All common block variables (decknames) with exceptions named
above start with a prefix that is also the same as the filename
of the comdeck.
Here is an example found in file comdeck 'hzd.cdk':
#if defined (DOC)
*
***comdeck hzd.cdk
*
*revision
* v2_10 - Qaddouri A. - initial version
* v2_30 - Desgagne & Desgagne - introduce pil_s, pil_n, pil_w, pil_e
* v3_00 - M. Desgagne - inlining of basic operators
*______________________________________________________________________
* |
* VARIABLES ASSOCIATED WITH HORIZONTAL DIFFUSION |
*______________________________________________________________________|
* | |
* NAME | DESCRIPTION |
*--------------------|-------------------------------------------------|
* HZD_MAX | maximum number of operators in Hzd_xp0_8 |
* Hzd_type_S | type of horizontal diffusion |
* Hzd_fact_L | .true. to get factorized hor. diffusion |
* Hzd_xp0_8 | east-west projection operators |
* Hzd_cdiff | coefficient for diffusion |
*----------------------------------------------------------------------
*
#endif
integer Hzd_pwr,HZD_MAX
parameter (HZD_MAX = 100)
character*12 Hzd_type_S
logical Hzd_fact_L
real*8 Hzd_xp0_8(HZD_MAX)
real Hzd_cdiff
common /hzdc/ Hzd_type_S
common /hzdl/ Hzd_fact_L
common /hzdi/ Hzd_cdiff, Hzd_pwr
common /hzdr/ Hzd_xp0_8
- revision when a comdeck is modified, a revision must be
included; try to be as specific as
possible. NO dates.
repeat the the version number
(characters "* vx_yy") at the beginning
of all lines and respect column alignments:
Use "name et al." when more than 2 persons
contributed to a revision.
for a new deck use "initial version"
- documentation use the format of the example as a template
- commons for the names of the commons, we add the
following extensions to the name of the common block
l (logical), s/c (character), r (real), i (integer),
if only one common is necessary, it can be the
same as the name of the comdeck
it is mandatory to put character variables
in a separate common (see example above)
----------
Subroutine
----------
Here is an example of a subroutine 'hzd_ho.ftn' that shows how
it is documented and the naming conventions. Note the naming of
the formal parameters (arguments) of the routines
***s/r hzd_ho - applies horizontal diffusion
*
#include
*
subroutine hzd_ho ( F_u, F_v_8, F_psd,.....DIST_SIZ,NK)
integer DIST_DIM, NK
real F_u(DIST_SHAPE,NK)
real*8 F_v_8(DIST_SHAPE,Nk)
*author
* Abdessamad Qaddouri
*
*revision
* v2_10 - Qaddouri A. - initial version
* v2_21 - Desgagne M. - control for diffusion on momentum only
*object
* The diffusion includes: second order(Hzd_pwr=1),
*arguments
* Name I/O Description
*----------------------------------------------------------------
* F_u I/0 U wind component
* F_v_8 I/0 V wind component
*implicits
#include "glb_ld.cdk"
#include "glb_pil.cdk"
#include "hzd.cdk"
*modules
integer fstecr
external fstecr
.
.
logical printout_L
integer i0,j0,in,jn
real*8 coef_8
character*12 typ_S
.
.
if (printout_L .and. typ_S.eq.Hzd_type_S) then
print *,'F_v_8*coef_8=',coef_8*F_v_8(i0,j0)
endif
.
.
All of the elements listed here are mandatory.
- ID section always use "***s/r name - short description"
- model_macros_f.h sometimes this 'include' is needed to interpret
macros (even in the interface); for this reason
always put it between the ID section and the
subroutine statement when needed
- subroutine ... self-explicit
- impnone self-explicit
- author free style
- revision include a revision statement for every modification
done; see description in comdeck section above
- object don't include the name of the subroutine
include any relevant information about the work
performed in this routine, scheme used, ...
if the ID section is clear enough and nothing
else needs to be mentioned, just use:
"see id section"; see example
- arguments Every argument of a subroutine/function must be
described according to the provided template.
The arguments must appear in order of appearance
in the interface.
- implicits regroup all comdecks included in this section.
do not use any "constant" section.
- modules to be used for "external" declaration of functions
for which we also have to declare the type
On some occasions we see an extra section called "notes". However,
the information found under this section should be moved under the
section "object".
-----------------------------------------------------------------------
Renaming of subroutines is mandatory when changing the calling sequence
-----------------------------------------------------------------------
A completely different name could be given to that new deck.
However it would be useful to keep a name as close as possible to
the former name. The new name can for example be constructed using
the following rule:
subroutine abc becomes abc_2 (underscore mandatory)
in the same manner:
subroutine abc_2 becomes abc_3
In this case, list of revisions is kept intact and we just include
a revision saying that the deck was renamed due to a change in the
calling sequence