From 155cda9c63c69fa9eedc1c0b906f4e1a867305fd Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 22 Dec 2019 17:06:15 -0500 Subject: [PATCH] doc: style guide based on comments in #3 --- STYLE_GUIDE.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 008496d12..7c4c2fd85 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,3 +1,66 @@ # Fortran stdlib Style Guide -This document will describe the code style to use. +> [A]utomate and codify as much as you possibly can while remembering that the human touch is still necessary to praise +> and be kind to your contributors. +> Let robots handle your project’s pedantry and humans handle your project’s empathy. + +-- @mikemcquaid, [Homebrew] project leader[1] + +[1]: https://mikemcquaid.com/2018/06/05/robot-pedantry-human-empathy/ +[Homebrew]: https://brew.sh + +## File naming conventions + +- Source files should contain at most one `program` or `module`/`submodule`. +- The filename should match the program or module name and have the file extension `.f90` or `.F90` if preprocessing is required. +- 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 `tests` subdirectory and have the same name as the module they are testing with the `test_` prefix added. E.g., `string_class.f90` and `tests/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. + +* __TABs vs spaces__: __Spaces__: TABs should never be used for indentation +* __Trailing whitespace__: All trailing whitespace must be removed +* __End of File (EOF)__: The file must end in a single new-line character +* __Line length__: __132__: The Fortran 90 (and later) standard mandates lines be no longer than 132 characters +* __Indentation__: __Two (2) spaces__ for all control constructs, line continuations, etc. +* __Line ending character__: __Native__: Git will convert line endings to `\n` (Unix style) on commit, and will checkout files with native line endings + +## Variable naming + +Variable names should be descriptive, and not artificially short. +By default, where it makes sense to do so, variable names shall be made up of one or more full words separated by an underscore. +For cases where a conventional & appropriate shortening of a word is used then the underscore may be omitted. + +Examples: + +__GOOD__: + +``` fortran +logical :: has_failed +real function linspace(...) +``` + +__BAD__: + +``` fortran +logical :: has_failed +real function lin_space(...) +``` + +## Keyword case + +Fortran keywords should __*not*__ be UPPERCASE. +Modern editors and IDEs can highlight Fortran syntax and UPPERCASE keywords. +UPPERCASE keywords give Fortran source code the appearance of being antiquated. + +## 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 __NOT__ include procedure names, `module` names and `program` names in the `end` statement. +There should only ever be one `program` and `module` statement per file and therefore including the name provides no useful information. +An exception to this rule is for procedures (`function`s and `subroutine`s) that are longer than a page of text. +Long procedures often are a sign of poor abstraction, however, sometimes they are necessary. +In such cases, the procedure name may be included in the `end` procedure statement.