Fortran standards and style guide

Introduction

This is a working collaborative document which will outline standard working procedures and coding style for ORCHIDEE. Please make comments by logging into the wiki and editing the page code using the discussion markup, followed by your initials. Comments will then be reviewed and merged into the main text periodically.

Example:

Sample text
> I don't understand this at all (BB)
>> This needs further clarification (JB)

which will then appear in the document as:

Sample text

I don't understand this at all (BB)

This needs further clarification (JB)

Interfaces

Existing structure and interactions between module and subroutines and how to improve it

1) For function/suroutine calls, there should only be five arguments per line.

CALL subroutine(arg1, arg2, arg3, arg4, arg5, &
                arg6, arg7, ... )

The reason is that subroutine arguments are not strictly checked, so when one is hunting for bugs, it's nice to be able to quickly check that all the arguments are in the right place.

READABILITY

Layout of code for clarity to the reader, reminder about the commenting style and ensuring interaction with the documentation compiler (dOxygen)

2) Related to point one, in the variable declaration of the subroutine, it's nice to have all the variables which are passed to/from to be in the same order as they are listed.

SUBROUTINE subroutine(arg1, arg2, arg3, arg4, arg5, &
                arg6, arg7, ... )

    !
    !! 0. Variable and parameter declaration
    !

    !
    !! 0.1 Input variables
    !
    INTEGER(i_std), INTENT(in)                                :: arg1         !! Domain size (unitless)
    REAL(r_std), INTENT (in)                                  :: arg2         !! Time step (s)
    REAL(r_std),DIMENSION (kjpindex), INTENT (in)             :: arg3         !! Downwelling short wave flux 
                                                  
   !
    !! 0.2 Output variables
    !
    INTEGER(i_std), INTENT(out)                               :: arg4         !! Domain size (unitless)
    REAL(r_std), INTENT (out)                                 :: arg5         !! Time step (s)
    REAL(r_std),DIMENSION (kjpindex), INTENT (out)            :: arg6         !! Downwellin

   !! 0.3 Modified variables
    !
    INTEGER(i_std), INTENT(inout)                             :: arg7         !! Domain size (unitless)

DEFINITION OF VARIABLES

Choosing where and when to define particular variables; portability between compilers; allocation/de-allocation of arrays etc.

OPTIMISING FOR SPEED

guidelines for making loops more efficient, eliminating dead code