----------- 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


Variables Naming Convention

  Variable names have the generic form:

        * real          no postfix
        * real*8        _8
        * integer       no postfix
        * logical       _L
        * character     _S


        * 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