Code Style Guidelines

The following guidelines are to be employed when writing new Fortran code. When applicable, please update existing code to also match this style.

• Fortran standard: 2018 (Intel compiler has it listed as 2015, gcc as 2018)
• Use upper case when declaring a Fortran command (e.g., IF, DO, SELECT CASE, ABS, SIZE, ATAN, etc.)

SELECT CASE ()
CASE ()
END SELECT

• Use an indention of 4 spaces. This should be employed inside of SELECT blocks, IF/THEN, DO loops, CONTAINS, etc.

IF (k == 1) THEN
    val = 1.0
ELSE
    val = 0.0
END IF

• Always declare all variables and their kind. Use IMPLICIT NONE and the Kinds module.

USE Kinds, ONLY : ipk, r8k
IMPLICIT NONE
INTEGER(ipk) :: i
REAL(r8k)    :: val

• List the intents (IN, OUT, INOUT) of all variables passed through call statements.

SUBROUTINE foo (val1, val2, val3)
USE Kinds, ONLY : r8k
IMPLICIT NONE
REAL(r8k), DIMENSION(:), INTENT(IN)    :: val1
REAL(r8k),               INTENT(INOUT) :: val2
REAL(r8k),               INTENT(OUT)   :: val3

• When possible, add FORD style comments. Comments need to be after (to the right or on the following line) what they are commenting

!! This is a comment
REAL(r8k) :: thcon   !! Thermal conductivity

• Do not use GOTO statements. If needed, use EXIT to terminate DO loops
• Do not use fixed array sizes. All run-time determined arrays should be ALLOCATABLE. If not a run time determination, array can be fixed but do not hard wire in a value. Instead, use a parameter and size the array based on that parameter.

REAL(r8k), DIMENSION(:), ALLOCATABLE :: val

INTEGER(ipk), PARAMETER :: n_dims = 13
REAL(r8k), DIMENSION(n_dims) :: val

• When adding new code, always include the author, date, and a description of the subroutine/function using FORD syntax. If any variables are passed, include description and units of the variable as a FORD comment on the line after the variable declaration or on the same line as the variable declaration. If implementing a correlation, add the reference from which is was taken. Multiple authors can be specified in the FORD metadata but for more complicated edits, please include those details in the function summary text (e.g. !! first coded by J. Smith of BigGovAgency in Month of Year, hacked at by J. Doe and C.M. Buttes of OtherAgency in January 3091.) You may (and should) specify the original Author and date using FORD metadata, and optionally you may specify the !! summary: ... meta data (equivalent to !>@brief ... however, it is usually easier and more flexible to just put the summary text following meta data entries in FORD comments. The first paragraph of FORD comments for the entity being documented will be taken as the brief/summary description when the !! summary: ... meta data is not provided. Please note that for FORD metadata to be correctly interpreted, it must be the very first FORD comment line of an entity, not even blank FORD style comments may precede it. To continue a meta-data entry the next line must be indented by at least 4 spaces. The FORD wiki has relatively thorough documentation on writing documentation, modifying the output with the project file and running FORD to produce the documentation. However, this later step is already integrated into the CMake based build system. Some additional guidelines for FORD usage and this project are available on the dedicated MORFEUS FORD usage wiki page.

SUBROUTINE foo (me, you)
!! author: Ian Porter, GSE
!! date: 02/12/2018
!!
!! Subroutine converts me to you
!! -----------------------------
!!
!! Additional details in markdown text here to be printed with procedure API documentation.
!! You should be able to include LaTeX style inline formulae $ \pi = 3.14159 $ as well as block formulae
!!
!! @warning
!! special paragraph environments are available
!!
!! @todo
!! describe `@bug` and `@todo` environment
!!
!! $$
!! x=\frac{1+y}{1+2z^2}
!! $$
!!
!! Reference:
!!
!! 1) xxx (you can link to the reference with standard markdown link syntax)
!!

USE Kinds
IMPLICIT NONE

CLASS(person_class), INTENT(IN) :: me
!! Class containing ...
CLASS(person_class), INTENT(OUT) :: you
!! you - Class containing

• An [AWK script] can be used (*nix systems) to automatically convert old Doxygen based documentation to FORD syntax, however, please check the output for errors. General conversion requires a full and robust parsing, which is not easily implemented. The AWK script reads input from standard input and writes output to standard output, to discourage completely blind wholesale conversion without some inspection. Example usage:

./to_ford.awk < /path/to/source_to_convert.f90 > converted_source.f90
# open and review converted_source.f90, e.g.,
less converted_source.f90
# If everything looks good replace old source and check into VCS
mv converted_source.f90 /path/to/source_to_convert.f90
git add /path/to/source_to_convert.f90
git commit -m "Converted doxygen to FORD in source_to_convert.f90"

• No common blocks!
• Use Modules

MODULE vars
    IMPLICIT NONE
    CONTAINS
        SUBROUTINE dummy ()
        END SUBROUTINE dummy
END MODULE vars

• File extension is .f90
• Use >, <, ==, etc. rather than .gt., .lt., .eq.