Naming conventions in the Feat2 package

The Feat2 package has been created using a set of strong naming convention rules that help the programmer to read and understand also unknown code. The following sections contain a brief overview about these rules. New programmers should deeply study these rules and follow them whereever possible.

Filename restrictions

  • The filename of a module file has to match the name of the module (plus an attached ".f90"). So a module "fsystem" implies a filename "fsystem.f90", a module "linearsystemblock" implies the filename "linearsystemblock.f90".

  • Filenames and module names shall be <= 31 characters long (this is a Fortran restriction).

Source code indention

Readibility is reatly enhanced by appropriate usage of text indention. The general rules are as follows:

  • A new block is indented by two spaces.
  • If a command is spanned over multiple lines, starting from the second line, there is an indention by four spaces.
  • Definitions of input/output variables in subroutines/functions shall be in the same column as the definition of the subroutine/function.
  • Internal variables of a subroutine are indented by two spaces, aligned with the code.

Here an example of a module defintion:

module mymodule

  use anothermodule1
  use anothermodule2

contains

  subroutine sub1(a,b,c)

  integer, intent(in) :: a
  integer, intent(in) :: b
  integer, intent(out) :: c

    integer :: i
    integer :: j

    call somesubroutine ("Some text","more text", &
        "next line", "even more test", &
        a, b, c)

    if (a .lt. b) then
      c = 1
    else
      j = 1
      do i=1,10
        j = j + 1
      end do
      c = j
    end if

  end subroutine

end module

Naming conventions of variables and types

Variable names follow a specific scheme which allows the reader to derive the type of the variable from the first letter(s). The following rules apply here:

  • All names should be self-descriptive.

  • Standard (non-pointer, non-array, non-handles) variables start with a lowercase letter that defines the type. Structures are generally referred to by "r". The second letter is lowercase as well. Variable names containing multiple words shall use an uppercase letter for every new word ("CamelCase"). Instructive example:

    imyNewVariable    - integer variable
nmyNewVariable    - integer variable with the meaning of a maximum number
cmyNewVariable    - integer variable with a fixed value set
                    (e.g., values of constants)
fmyNewVariable    - float type variable (REAL(SP))
dmyNewVariable    - double precision variable (REAL(DP))
qmyNewVariable    - quadrupel precision variable (REAL(QP))
smyNewVariable    - string variable
bmyNewVariable    - boolean variable
rmyNewVariable    - An arbitrary structure.

  • If the variable is an array, the first letter is to be set upper case. The letter "C" is in this case reserved for character arrays. Instructive example:

    ImyNewVariable    - array of integers
FmyNewVariable    - array of single precision variables
DmyNewVariable    - array of double precision variables
QmyNewVariable    - array of quadruple precision variables
SmyNewVariable    - array of string variable
CmyNewVariable    - array of characters
BmyNewVariable    - array of boolean variable
RmyNewVariable    - array of a structure

  • If the variable is a handle identifying an array, a "h_" precedes the name. Instructive example:

    h_ImyNewVariable  - handle to array of integers
h_FmyNewVariable  - handle to array of single precision variables
h_DmyNewVariable  - handle to array of double precision variables
h_QmyNewVariable  - handle to array of quadrupel precision variables
h_BmyNewVariable  - handle to array of boolean variable

  • If the variable is a pointer to an object, a "p_" precedes the qualifier. Instructive example:

    p_imyNewVariable  - pointer to integer variable
p_fmyNewVariable  - pointer to float type variable (REAL(SP))
p_dmyNewVariable  - pointer to double precision variable (REAL(DP))
p_qmyNewVariable  - pointer to quadrupel precision variable (REAL(QP))
p_smyNewVariable  - pointer to string variable
p_bmyNewVariable  - pointer to boolean variable
p_rmyNewVariable  - Pointer to structure

    p_ImyNewVariable  - pointer to array of integers
p_FmyNewVariable  - pointer to array of single precision variables
p_DmyNewVariable  - pointer to array of double precision variables
p_QmyNewVariable  - pointer to array of quadrupel precision variables
p_BmyNewVariable  - pointer to array of boolean variable
p_RmyNewVariable  - Pointer to array of structures

  • Structure are generally declared with a "t_" preceding the structure name. Example:

    type t_timer
  ...
end type

  • Constants are written completely in uppercase letters. They shall start with an identifier (plus underscore) that refers to the module where the constant is defined. Instructive examples:

    EL_Q1     - Defines the Q1 element. Constant from "element.f90".
CUB_G2X2  - Refers to the 2x2 Gauss rule. Constant from "cubature.f90"

Naming conventions for subroutines and functions

  • Subroutines and functions shall start with an identifier (plus underscore) that refers to the module where the constant is defined. The complete identifier has to be <= 31 characters in length (by the Fortran standard). Instructive examples:

    subroutine tria_readTriFile2D    - triangulation.f90
subroutine tria_done             - triangulation.f90

subroutine sys_halt              - fsystem.f90
subroutine sys_upcase            - fsystem.f90

subroutine lsyssc_createVector   - linearsystemscalar.f90
subroutine lsyssc_scalarProduct  - linearsystemscalar.f90

subroutine lsysbl_createVector   - linearsystemblock.f90
subroutine lsysbl_scalarProduct  - linearsystemblock.f90

Exceptions

  • Parts of names that are abbreviations in themselves can be capitalised even if they violate the above rules. They are not capitalised if they appear as a first component of a name. Example:

    iid      - is ok.
iID      - is wrong.
dtimeCPU - is ok.
dtimeCpu - is ok.

  • The rules shall hold for all public identifiers for modules. Internal identifiers (i.e., variables, constants, subroutines, functions) which are not public should follow these rules as well but may violate them for a good reason.

  • Self explaining variables (like a small "i" or "j" identifying a running index for a DO loop, e.g.) are allowed to be used in subroutines/functions as long as they are non-public.