Merge pull request #42 from zbeekman/style-enforcement

Style guide (see #3)

Author: milancurcic

Diff for: .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 for: .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 for: 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 <kbd>Tab</kbd> 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 <scope> 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.