Adopting a consistent style can improve code legibility through the choice of good naming conventions.
In addition, style checks will be run during CI to flag any severe non-conformance.
This allows code review discussions to focus on semantics and substance rather than pedantry.
Consistent whitespace usage, and not polluting line endings with trailing white space makes git diff
s considerably more legible.
This style guide is a living document and proposed changes may be adopted after discussing them and coming to a consensus.
- Do not use obsolescent or deleted language features
E.g.,
common
,pause
,entry
, arithmeticif
and computedgoto
- Do not use vendor extensions in the form of non-standard syntax and vendor supplied intrinsic procedures
E.g.,
real*8
oretime()
, usereal(pr)
- Variable and procedure names, as well as Fortran keywords, should be written in lowercase
- All constants (like the
R
gas constant) should be upper case - All variables should be in lowercase unless they are represented in uppercase in the bibliography.
for example, the molar volume would be
v
and the total volume would beV
. - In the case of derivatives, for general properties they should be written as
dXdy
for first derivatives anddXdyz
ordXdy2
for second order derivatives. The only exception is with energetic properties, likeAr
, where derivatives are written likeArV
,ArVn
, etc. - All thermodynamic variables that are input of a subroutine/function should
have the order:
n, V, T
n, P, T
- Variable and procedure names should be made up of one or more full words separated by an underscore,
for example
has_failed
is preferred overhasfailed
- Where conventional and appropriate shortening of a word is used then the underscore may be omitted,
for example
linspace
is preferred overlin_space
- For derived types use CamelCase, like
ArModel
- Source files should contain at most one
program
,module
, orsubmodule
- The filename should match the program or module name and have the file extension
.f90
or.F90
if preprocessing is required module
names should include it's subdirectory, usingyaeos__
for the parentsrc
directory. For example the module insrc/phase_equilibria/flash.f90
should be namedyaeos__phase_equilibria_flash
.- If the interface and implementation is split using submodules the implementation submodule file should have the same name as the
interface (parent) module but end in
_implementation
E.g.,string_class.f90
andstring_class_implementation.f90
- Tests should be added in the
test
subdirectory and have the same name as the module they are testing with thetest_
prefix added E.g.,string_class.f90
andtest/test_string_class.f90
By setting and following a convention for indentation and whitespace, code reviews and git-diffs can focus on the semantics of the proposed changes rather than style and formatting.
We recommend enforce the use of findent
to format your files.
- The body of every Fortran construct should be indented by three (3) spaces
- Line length should be limited to 80 characters and must not exceed 132
- Do not use Tab characters for indentation
- Remove trailing white space before committing code
- Always specify
intent
for dummy arguments. - Don't use
dimension
attribute to declare arrays because it is more verbose. Use this:instead of:real, allocatable :: a(:), b(:,:)
real, dimension(:), allocatable :: a
When defining many arrays of the same dimension,real, dimension(:,:), allocatable :: b
dimension
can be used as an exception if it makes the code less verbose. - If the
optional
attribute is used to declare a dummy argument, it should follow theintent
attribute.
Fortran allows certain block constructs or scopes to include the name of the program unit in the end statement.
The convention adopted herein is to include procedure names, module
names and program
names in the end
statement,
unless the closing statement can reasonably be expected to be on the same screen or page, within about 25 lines.
Documentation strings should be provided for all public and protected entities and their arguments or parameters. This is currently accomplished using the FORD tool. For help writing FORD style documentation please see the FORD wiki. The following two sections are most relevant for contributing new code:
To write the "spec" (specification) for a new proposal, please place it in the
FORD "pages" directory at
doc/specs/
.
To get help please see the "Writing Pages"
and "Writing Documentation" pages
on the FORD wiki.