Guide for good coding

How to create a new module/subroutine

Subroutines should be integrated inside a module. A good writing habit is to add the line "IMPLICIT NONE", in the beginning of the module and subroutine.

First you can define all the variable that belongs to the module and could be used at another place. A good thing is also to create a subroutine that allocate and initialise module variables. If the variable is only modified inside the module it should be taged as protected. If the variable belongs only to the module it can be specified to be private.

You can now start the definition of the subroutine. Start by variable and function from other module if necessary. Comment the purpose of the subroutine directly. Declare the variables, first the one pass in arguments. Use the intent to specify the status of the variable inside the subroutine. Continue with the local and saved variables. Then you can define local variables. Remember to comment all of them, you can specify the dimension if the variable is an allocatable variable as well as the units and everything that seems appropriate.

You can finally write the code.

 1       MODULE aquarium_mod
 2 
 3       IMPLICIT NONE
 4 
 5       INTEGER :: water     ! Define what is the variable, the dimension, units (°) etc...
 6       REAL,SAVE,ALLOCATABLE,DIMENSION(:) :: kre1      ! Another comment 
 7 
 8       CONTAINS
 9 
10       SUBROUTINE aquarium(kre, grass, other_things
11      &   really_anything)
12                                                          
13       use another_module_mod, only: fct, variable
14       
15 !=======================================================================
16 !   subject:
17 !   --------
18 !   What is the subroutine doing
19 !
20 !   author: Someone smart 
21 !   ------
22 !   update: Someone smarter, march 2012:
23 !         - I change something here
24 !   
25 !=======================================================================
26       
27        IMPLICIT NONE
28 
29 !-----------------------------------------------------------------------
30 !
31 !    Declarations :
32 !    --------------
33 !
34 !    Input/Output
35 !    ------------
36 
37       REAL, INTENT(IN)    ::  something(ngrid,nlayer) ! 2D tabular used as an input only  (W/m^2)
38       REAL, INTENT(OUT)   ::  kre(ngrid)              ! 1D tabular output by the subroutine  
39       REAL, INTENT(INOUT) ::  grass(ngrid,nlayer)     ! Variable that is modified by the subroutine
40                                                       ! it is an input and output
41       LOGICAL,INTENT(IN)  ::  really_anything         ! Boolean variable  
42 
43 !    Local saved variables :
44 !    -----------------
45       INTEGER, PARAMETER :: nb_kre = 6                ! Number of kre
46       INTEGER, SAVE      :: rock                      ! Another variable
47       LOGICAL,SAVE :: firstcall=.true.                ! Another variable
48 
49 !    Local variables :
50 !    -----------------
51       REAL tabular(ngrid)                             ! Local var
52       INTEGER i                                       ! Loop var
53 
54 !    Beginning of the code :
55 !    ----------------- 
56 
57       IF (firstcall) THEN
58         ! identify where are the kre
59         DO i=1,nb_kre
60           kre(i)=i
61           write(*,*) "the Kre ", i, "is behind the rock"
62         ENDDO !end of the loop nb_kre
63       ENDIF   !end firstcall
64 
65       END SUBROUTINE aquarium
66 
67 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
68 
69       SUBROUTINE ini_aquarium(ngrid)
70 !=======================================================================
71 !   Initialise module's variable
72 !=======================================================================
73       IMPLICIT NONE
74       INTEGER, INTENT(IN) :: ngrid
75 
76       allocate(kre1(ngrid+1))
77 
78       END SUBROUTINE ini_aquarium
79 
80 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
81 
82       SUBROUTINE end_aquarium
83 !=======================================================================
84 !   Deallocate module's variable
85 !=======================================================================
86 
87       IMPLICIT NONE
88 
89       IF (allocated(kre1)) deallocate(kre1)
90 
91       END SUBROUTINE end_aquarium
92       
93       END MODULE aquarium_mod

How to pass variable to subroutine (by argument or by module)

Define when we should use argument and when to use modules

Naming variables convention

What is the naming convention. In vdifc_mod for exemple.

Loop index convention

Index name for loops through:

• physical grid : ig (max ngrid)
• vertical levels : l (max nlayer)
• tracer : iq (max nq)
• subslopes : islope (max nslope)

iaer=1,naerkind

Efficient loop coding

The more outside loop should correcpond to the last index of an array.

Example:

      DO l=1,nlayer
        DO ig=1,ngrid
          array(ig,l)=l*ig
        ENDDO
      ENDDO

How to use the Intent

Argument of a function can come in 3 different way: IN, OUT, INOUT.

How to comment code

• In english
• As much as possible
• Variable definition : explain what it is, the dimension, the units etc...
• Subroutine : Explain what it does, who wrote it, who modify it and why if it is a big change
• Loops : if the enddo is far away you can comment to which index it correspond to.
• Chapter your code : you can add section to your code to make it clearer.

General guide

• Create .F90 instead of .F
• Delete unused argument in a function call if you see one
• Delete unused variables
• Choose meaningful names of variables
• Don't hesitate to comment at much as possible, a code is never too commented
• Delete unused commented code lines