diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..b13434bad --- /dev/null +++ b/.editorconfig @@ -0,0 +1,55 @@ +# EditorConfig file. For more info, please see: +# https://EditorConfig.org + +# top-most EditorConfig file +root = true + +# All files should have a final newline and not have trailing whitespace +# but we need to explicitly enumerate files we care about to prevent random junk +# from being linted + +[*.{f90,F90}] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +max_line_length = 132 +insert_final_newline = true + +[{CMakeLists.txt, *.cmake}] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +max_line_length = 132 +insert_final_newline = true + +[*.md] +max_line_length = off +trim_trailing_whitespace = false +charset = utf-8 +insert_final_newline = true + +# Tab indentation (no size specified) +[Makefile] +indent_style = tab +indent_size = 4 +trim_trailing_whitespace = true +max_line_length = 132 +insert_final_newline = true + +[*.sh] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +max_line_length = 132 +insert_final_newline = true + +[*.nml] +trim_trailing_whitespace = true +max_line_length = 132 +insert_final_newline = true + +[*.{yml,json}] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +insert_final_newline = true diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..55095e948 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,31 @@ +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +*.c text +*.h text +*.f90 text +*.F90 text +*.md text +*.txt text +*.sh text +*.cu text + +# Denote all files that are truly binary and should not be modified. +*.mod binary +*.o binary +*.a binary +*.so binary +*.tar binary +*.gz binary +*.tgz binary + +# Prevent dev-ops files from making it into the release archives +.gitattributes export-ignore +.gitignore export-ignore +codecov.yml export-ignore +.github export-ignore + +# Perform substitutions when `git export`ing these files +.VERSION export-subst diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 008496d12..5860d6c02 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,3 +1,49 @@ # Fortran stdlib Style Guide -This document will describe the code style to use. +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 diff`s 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()` + +## 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 +* 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. + +* The body of every Fortran construct should be indented by __two (2) spaces__ +* Line length *should be limited to 80 characters* and __must not exceed 132__ +* Please do not use Tab characters for indentation +* Please remove trailing white space before committing code + +## Variable and procedure naming + +* Variable and procedure names, as well as Fortran keywords, should be written in lowercase +* 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` + +## 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.