Style Guidelines

The following constitute some initial guidelines for contributed code.

##General Principles Always state implicit none at the start of a module/program. It is unnecessary to state it within any internal procedures. Use statements should be accompanies with only clauses, although renaming module contents on imports is to be discouraged. Module contents should be private by default, with as few entities as possible declared public. Ideally, only a derived type, its constructor, and any useful parameters would be public. Furthermore, all components of a derived type should be private and should only be made available through getter and setter type-bound procedures.

As a rule of thumb, there should only be one derived type per module. An example of where an exception could be made can be seen in the container.f90 file. However, it is unlikely that any other such case will occur in FIAT.

All source code (with the obvious exception of strings and comments) should be lower case. Lines should be no more than 100 characters in length. Any continued line should be indented, although the exact level of indentation will be left up to the coder's discretion. Semi-colons (allowing two statements to be placed on the same line of the source file) should not be used.

##Indenting Files should start with no indentation. Every time you enter a new one of the following, an extra level of indentation should be added:

• module
• program
• procedure
• interface
• loop
• if/else-if/else block
• foreach block
• select case (with a further indentation for the code to be executed for each individual case)
• select type (with a further indentation for the code to be executed for each individual case)
• type
• etc.

Each indentation should be 2 spaces. A contains statement should have the same level of indentation as the module/program/procedure/type declaration that contains it. For example:

type example
  private
  integer :: i, j
contains
  procedure :: set_ints
end type example

##Commenting Comment extensively. Indent comments (including the exclamation mark) to the same level as the code which they are commenting. If a comment is placed at the end of a line of code, ensure that there is one space between the last character of code and the exclamation mark. In all comments, place a space between the exclamation mark and the start of the comment text.

A license notice, like the one below, should be placed at the top of all source files.

!
!  <filename>
!  This file is part of FIAT.
!
!  Copyright 2016 Christopher MacMackin <[email protected]>
!  
!  This program is free software; you can redistribute it and/or modify
!  it under the terms of the GNU Lesser General Public License as
!  published by the Free Software Foundation; either version 3 of the 
!  License, or (at your option) any later version.
!  
!  This program is distributed in the hope that it will be useful,
!  but WITHOUT ANY WARRANTY; without even the implied warranty of
!  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
!  GNU Lesser General Public License for more details.
!  
!  You should have received a copy of the GNU Lesser General Public
!  License along with this program; if not, write to the Free Software
!  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
!  MA 02110-1301, USA.
!  

Please add inline documentation to the code that can be parsed by FORD. The default characters for documentation comments should be used. Please place documentation comments after the start of whatever is being documented, using the default alternative docmark. The default normal docmark may be used if the the documentation is an inline comment or a comment only one line long. For modules, procedures, generic interfaces to module procedures, types, and programs, please specify metadata for the author and date originally written. For modules and programs please also add metadata specifying that the license is LGPLv3.

Documentation must be provided for all of the following: modules, types, procedures, dummy arguments, programs, and generic interfaces. In most cases documentation should also be provided for variables (including components of a derived type), although it need only be a few words. For type-bound procedures, documentation must be provided within the procedure itself, but does not necessarily have to be at the binding within the type declaration. Abstract interfaces generally need not be documented, while interfaces which are non-generic and non-abstract should not be used.

In documentation blocks, the metadata should be aligned. This means that there should be one space between the (alternative) docmark and the first line of metadata and two spaces between the comment character and each subsequent line of metadata. The body of the documentation should be separated from the comment character by one space only.

##Naming Conventions Names should be descriptive, especially for publicly visible entities. Underscores should be used to separate words if a name is more than two words long. If a name is only two words long then an underscore may be used at your discretion. Sometimes they make the name more readable, sometimes they just make it longer. As with anything else in the code, use lower cases characters only.

###Files Files should have the same base name as the module or program which they contain. In the case of modules, the file-name should not contain the _mod suffix (see below). The .f90 extension should be used (or .F90 if the preprocessor is required).

###Modules Modules names should be appended by _mod and should express whatever derived type is implemented therein. For example, node_mod, linked_list_mod, etc.

###Derived Types Type names should be as short as possible whilst remaining descriptive. Do not append the suffix _type to the name. Type-bound procedures should contain an action verb if they are in any way altering the state of a derived type, but those which simply provide information on the derived type need not.

###Procedures Generally, procedures should begin with an action verb. One exception to this is private procedures which are then bound to a type. If this is the implementation of an inherited deferred procedure or is overriding an inherited procedure then the name should take the form type-name_binding-name. If the procedure is part of a generic interface, either as in the form of an interface block or a type-bound procedure, then its name should take the form generic-name_distinguishing-feature. For example, an interface named convert_to_mks which provides a function able to accept different kinds of real values may have implementations named convert_to_mks_r4, convert_to_mks_r8, and convert_to_mks_r16.