CODE_STYLE.md

   1 # Coding Style
   2
   3 ## General
   4
   5 * Trim all trailing whitespace from every line (some editors can do this
   6   automatically).
   7 * No <Tab> characters.
   8 * Supply a header for each file with a description of the file and the author(s)
   9   name or GitHub ID.
  10 * A copy of the [Gnu Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0.en.html)
  11   must be included at the top of each file.
  12 * Documentation should be written so that it can be parsed by [Doxygen](http://www.doxygen.nl/).
  13 * All variables should be defined, and include units. Unit-less variables should be marked `unitless`
  14 * Provide detailed descriptions of modules, interfaces, functions, and subroutines
  15 * Define all function/subroutine arguments, and function results (see below)
  16 * Follow coding style of the current file, as much as possible.
  17
  18 ## Fortran
  19
  20 ### General
  21
  22 * Use Fortran 95 standard or newer
  23 * Two space indentation
  24 * Use `KIND` parameters from intrinsic fortran modules such as iso_fortran_env
  25   or iso_c_binding to ensure portability
  26 * Never use implicit variables (i.e., always specify `IMPLICIT NONE`)
  27 * Lines must be <= 120 characters long (including comments)
  28 * logical, compound logical, and relational if statements may be one line,
  29   using “&” for line continuation if necessary:
  30   ```Fortran
  31   if(file_exists(fileName)) call open_file(fileObj,fileName, is_restart=.false)
  32   ```
  33 * Avoid the use of `GOTO` statements
  34 * Avoid the use of Fortran reserved words as variables (e.g. `DATA`, `NAME`)
  35 * Avoid the use of `COMMON` blocks
  36
  37 ### Derived types
  38
  39 * Type names must be in CapitalWord format.
  40 * Variables names must be in underscore_word format.
  41 * All member variables must be private.
  42 * Doxygen description on the line before the type definition.
  43 * Inline doxygen descriptions for all member variables.
  44
  45 ## Functions
  46 * If a function has a result variable, it should be declared on its own line,
  47   and the variable should not be declared with a specific intent.
  48 * Inline doxygen descriptions for all arguments, except the result variable.
  49 * Doxygen description on the line(s) before the function definition.  This must
  50   specify what the function is returning using the `@return` doxygen keyword.
  51
  52 ## Blocks
  53 * terminate `do` loops with `enddo`
  54 * terminate block `if`, `then` statements with `endif`
  55
  56 ## OpenMP
  57
  58 * Directives should start at the beginning of the line, and be in lowercase.
  59 * All openMP directives should specify default(none), and then explicitly list
  60   all shared and private variables.
  61 * All critical sections must have a unique name.
  62
  63 ## Fortran Example
  64
  65 ```Fortran
  66
  67 !***********************************************************************
  68 !*                   GNU Lesser General Public License
  69 !*
  70 !* This file is part of the GFDL Flexible Modeling System (FMS).
  71 !*
  72 !* FMS is free software: you can redistribute it and/or modify it under
  73 !* the terms of the GNU Lesser General Public License as published by
  74 !* the Free Software Foundation, either version 3 of the License, or (at
  75 !* your option) any later version.
  76 !*
  77 !* FMS is distributed in the hope that it will be useful, but WITHOUT
  78 !* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  79 !* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  80 !* for more details.
  81 !*
  82 !* You should have received a copy of the GNU Lesser General Public
  83 !* License along with FMS.  If not, see <http://www.gnu.org/licenses/>.
  84 !***********************************************************************
  85
  86 !> @file
  87 !! @brief Example code
  88 !! @author <developer>
  89 !! @email gfdl.climate.model.info@noaa.gov
  90
  91 module example_mod
  92   use, intrinsic :: iso_fortran_env, only: INT32, REAL32
  93   use util_mod, only: util_func1
  94   implicit none
  95   private
  96
  97   public :: sub1
  98   public :: func1
  99
 100   !> @brief Doxygen description of type.
 101   type,public :: CustomType
 102     private
 103     integer(kind=INT32) :: a_var !< Inline doxygen description.
 104     real(kind=REAL32),dimension(:),allocatable :: b_arr !< long description
 105                                                         !! continued on
 106                                                         !! multiple lines.
 107   endtype CustomType
 108
 109   contains
 110
 111   !> @brief Doxygen description.
 112   subroutine sub1(arg1, &
 113     & arg2, &
 114     & arg3)
 115     real(kind=REAL32),intent(in) :: arg1 !< Inline doxygen description.
 116     integer(kind=INT32),intent(inout) :: arg2 !< Inline doxygen description.
 117     character(len=*),intent(inout) :: arg3 !< Long inline doxygen
 118                                            !! description.
 119   end subroutine sub1
 120
 121   !> @brief Doxygen description
 122   !! @return Function return value.
 123   function func1(arg1, arg2) result(res)
 124     integer(kind=INT32),intent(in) :: arg1 !< Inline doxygen description
 125     integer(kind=INT32),intent(in) :: arg2 !< Inline doxygen description
 126     integer(kind=INT32) :: res
 127   end function func1
 128
 129 end module example_mod
 130 ```
 131
 132 ## C/C++
 133
 134 ### General
 135 * C code is written in GNU style.  Each new level in a program block is indented
 136   by 2 spaces. Braces start on a new line, and are also indented by 2 spaces.
 137 * See the [Gnome C coding style guide](https://developer.gnome.org/programming-guidelines/stable/c-coding-style.html.en)
 138   for more information