Loading [MathJax]/extensions/tex2jax.js
GBS
All Classes Namespaces Files Functions Variables Enumerator Macros Modules Pages
Contributing to the code

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

  1. 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.
  2. 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.
  3. Work on your feature branch as usual, i.e. git add, git commit, etc..
  4. Document your code and add tests.
  5. 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
    ! First the Fortran intrinsic modules (in alphabetical order)
    use intrinsic_a_mod, only: var_a
    use intrinsic_b_mod, only: var_b
    ! Then third-party and local modules (in alphabetical order)
    use a_mod, only: subroutine_a
    use b_mod, only: subroutine_b
    ! Always use a single implicit none at the beginning
    implicit none
    ! Everything should be private by default
    private
    public :: ! Add your list of public entities
    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
    call my_subroutine(arg1, arg2, optional_arg=arg3)
    instead of
    call my_subroutine(arg1, arg2, arg3)
  • 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)