Coding guidelines and git workflow to contribute to the code development
Git configuration
If not already present, install git using your favorite package manager. To check if you already have git, you can type
> git --version
git version X.Y.Z
If you get an error, you need to install git.
Please, consider adding your information using the git config
:
git config --global user.name "John Doe"
git config --global user.email "john.doe@email.com"
git config --global core.editor emacs
These information are very useful to acknowledge the work of everyone, e.g. if the GBS project becomes open source.
If you already have a configuration in place, you can place yourself inside the GBS repository and use the --local
option instead of --global
.
Development workflow
The development of GBS uses a feature branch workflow. In this workflowm, the master
branch is tested and ready for production. No work should be done directly in this branch (except trivial changes, e.g. typos in the documentation)! All the development is done on so-called feature branches and whenever they are ready to be published (i.e. tests pass, documentation is added, and they sastisfy the coding guidelines), they are merged into master
.
Workflow step-by-step
- Get the latest version of the
master
> git pull --rebase origin master
- Note
- You must already be on
master
. This should not result in a conflict because you should not work directly on master
.
- Checkout to a new feature branch
> git checkout -
b feature/<feature_branch_name>
real(dp), dimension(:), pointer, public, protected b
Definition: time_integration_mod.F90:34
where feature/<feature_branch_name>
is a meaningful name that describe the work done on this branch, e.g. feature/improve_boundary_conditions
.
- Work on your feature branch as usual, i.e.
git add
, git commit
, etc..
- Document your code and add tests.
- Merge your code into master and tag the version with a short description of your changes.
Tips and tricks
- Try to merge the
master
branch into your feature branch as often as possible. It will avoid long and tricky merges at the end
- Each feature branch should address a single feature. Do not hesitate to create many feature branches
- Make small commits, each with a single intent in the code. This is much easier to review than large commits changing half the code.
Coding guidelines
Coding style
The following rules are mostly there to increase the uniformity of the code as well as its robustness. Remember that a code is generally written once, but read many times. It is therefore important for the general quality of the code to enforce a few cosmetic rules that will increase readabilty.
Files and general comments
- All the Fortran files use the
.F90
(capital F) extension
- File name is the same as the program unit it contains. For example, module
my_mod
should be in file my_mod.F90
.
- Only one module per file.
- Line length is limited to 132 characters.
- Use lower case Fortran intrinsics.
- Indentation is done using 2 spaces. Do not use the tab character.
- Do not put commented blank lines, just an empty line.
Fortran style
- All the modules should have the following structure
module my_mod
use intrinsic_a_mod, only: var_a
use intrinsic_b_mod, only: var_b
use a_mod, only: subroutine_a
use b_mod, only: subroutine_b
implicit none
private
public ::
contains
end module my_mod
- Append
_mod
to the module name.
- Always add the
only
clause with the use
clause. Do not import the whole module.
- Do not use external subroutines (every subroutine should be contained in a module)
- Always use the double colon after a type declaration, e.g.
integer :: a
- Use modern comparison operators, i.e.
==
, /=
, >
, <
, <=
, and >=
instead of .eq.
, .neq.
, .gt.
, .lt.
, .geq.
, and .leq.
.
- Use spaced ends, e.g.
end if
instead of endif
.
- Avoid as much as possible non-standard Fortran
- Fortran keywords, e.g. data, should not be used as variable names
- Fortran constant variables (
parameter
) are upper case
- Put a space before and after an operator (=, .and., <=, etc.), a punctuation sign ('.', ',', etc.)
- Add spaces between mathematical operators to lighten the code. Note that you can group some terms. For example, use
a = 2*b + c
instead of a = 2*b+c
- Do not use trailing whitespaces
- Use of global variables is (almost) always a bad idea
- When using subroutines/functions with optional arguments, always use their name instead of
- Derived types begin with a capital T and use camel case, e.g.
TMyCustomType
- Module names, functions/subroutines and variables use snake case, e.g.
my_variable
- One
implicit none
per module
- All the
use
statements at the top of the module
- In GBS, all the floating point numbers are represented using 64-bit precision. This is done using the
dp
kind. Use it for all the reals and the literals, e.g. real(dp) :: pi = 3.14159_dp
The dp
kind in literals is important because otherwise they are treated as 32-bit numbers!
Note that various editors allow you to automatize those coding conventions.
Editor configuration
Emacs
Adding the following lines to your Emacs configuration file, init.el
, will allow you to enforce a few coding rules.
;; Set most of the indentations to 2 spaces
(setq f90-do-indent 2)
(setq f90-if-indent 2)
(setq f90-type-indent 2)
(setq f90-program-indent 2)
;; Set indentation for line continuation to 4 spaces
(setq f90-continuation-indent 4)
;; Draw a line at column number 132 to have a visual limit for line length
;; Note that this requires you to install the Emacs package `fill-column-indicator`
(add-hook 'f90-mode-hook 'fci-mode)
(add-hook 'f90-mode-hook (lambda () (setq fci-rule-column 132)))
;; Remove trailing whitespaces
;; Note that this will remove trailing whitspaces for all the files you save,
;; not only .F90 files!
(add-hook 'before-save-hook 'delete-trailing-whitespace)