Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
100 lines (81 loc) · 5.72 KB

STYLE_GUIDE.md

File metadata and controls

100 lines (81 loc) · 5.72 KB

yaeos Style Guide

Adopting a consistent style can improve code legibility through the choice of good naming conventions. In addition, style checks will be run during CI to flag any severe non-conformance. This allows code review discussions to focus on semantics and substance rather than pedantry. Consistent whitespace usage, and not polluting line endings with trailing white space makes git diffs considerably more legible. This style guide is a living document and proposed changes may be adopted after discussing them and coming to a consensus.

Use (modern) standard Fortran

  • Do not use obsolescent or deleted language features E.g., common, pause, entry, arithmetic if and computed goto
  • Do not use vendor extensions in the form of non-standard syntax and vendor supplied intrinsic procedures E.g., real*8 or etime(), use real(pr)

Naming of variables and constructs

  • Variable and procedure names, as well as Fortran keywords, should be written in lowercase
  • All constants (like the R gas constant) should be upper case
  • All variables should be in lowercase unless they are represented in uppercase in the bibliography. for example, the molar volume would be v and the total volume would be V.
  • In the case of derivatives, for general properties they should be written as dXdy for first derivatives and dXdyz or dXdy2 for second order derivatives. The only exception is with energetic properties, like Ar, where derivatives are written like ArV, ArVn, etc.
  • All thermodynamic variables that are input of a subroutine/function should have the order:
    • n, V, T
    • n, P, T
  • Variable and procedure names should be made up of one or more full words separated by an underscore, for example has_failed is preferred over hasfailed
  • Where conventional and appropriate shortening of a word is used then the underscore may be omitted, for example linspace is preferred over lin_space
  • For derived types use CamelCase, like ArModel

File naming conventions

  • Source files should contain at most one program, module, or submodule
  • The filename should match the program or module name and have the file extension .f90 or .F90 if preprocessing is required
  • module names should include it's subdirectory, using yaeos__ for the parent src directory. For example the module in src/phase_equilibria/flash.f90 should be named yaeos__phase_equilibria_flash.
  • If the interface and implementation is split using submodules the implementation submodule file should have the same name as the interface (parent) module but end in _implementation E.g., string_class.f90 and string_class_implementation.f90
  • Tests should be added in the test subdirectory and have the same name as the module they are testing with the test_ prefix added E.g., string_class.f90 and test/test_string_class.f90

Indentation & whitespace

By setting and following a convention for indentation and whitespace, code reviews and git-diffs can focus on the semantics of the proposed changes rather than style and formatting.

We recommend enforce the use of findent to format your files.

  • The body of every Fortran construct should be indented by three (3) spaces
  • Line length should be limited to 80 characters and must not exceed 132
  • Do not use Tab characters for indentation
  • Remove trailing white space before committing code

Attributes

  • Always specify intent for dummy arguments.
  • Don't use dimension attribute to declare arrays because it is more verbose. Use this: 
    real, allocatable :: a(:), b(:,:)
    instead of: 
    real, dimension(:), allocatable :: a

    real, dimension(:,:), allocatable :: b
    When defining many arrays of the same dimension, dimension can be used as an exception if it makes the code less verbose.
  • If the optional attribute is used to declare a dummy argument, it should follow the intent attribute.

End block closing statements

Fortran allows certain block constructs or scopes to include the name of the program unit in the end statement. The convention adopted herein is to include procedure names, module names and program names in the end statement, unless the closing statement can reasonably be expected to be on the same screen or page, within about 25 lines.

Document public API code with FORD

Documentation strings should be provided for all public and protected entities and their arguments or parameters. This is currently accomplished using the FORD tool. For help writing FORD style documentation please see the FORD wiki. The following two sections are most relevant for contributing new code:

To write the "spec" (specification) for a new proposal, please place it in the FORD "pages" directory at doc/specs/. To get help please see the "Writing Pages" and "Writing Documentation" pages on the FORD wiki.