From 26d5954099dcd5f26e1d010486ca10d6a6cfb29e Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 22 Dec 2019 15:54:20 -0500 Subject: [PATCH 01/14] Add `.editorconfig` file for correct indentation * Most editors respect `.editorconfig` settings. * For those that don't out of the box plugins are readily available for all major editors at https://editorconfig.org/#download --- .editorconfig | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .editorconfig 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 From d1dcc8b8b7ecdbef42511b98177c41a271daaac6 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 22 Dec 2019 17:15:44 -0500 Subject: [PATCH 02/14] Ensure line endings are handled by git Checkout/commit native line endings, even if users don't have `core.autocrlf` set. --- .gitattributes | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .gitattributes 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 From f72beb1cdc8d6d930bda4218b9f8e389caeab63d Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 22 Dec 2019 17:06:15 -0500 Subject: [PATCH 03/14] doc: style guide based on comments in #3 --- .editorconfig | 6 ++--- STYLE_GUIDE.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 67 insertions(+), 4 deletions(-) diff --git a/.editorconfig b/.editorconfig index b13434bad..0252cf222 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,14 +10,14 @@ root = true [*.{f90,F90}] indent_style = space -indent_size = 2 +indent_size = 4 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true [{CMakeLists.txt, *.cmake}] indent_style = space -indent_size = 2 +indent_size = 4 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true @@ -38,7 +38,7 @@ insert_final_newline = true [*.sh] indent_style = space -indent_size = 2 +indent_size = 4 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 008496d12..8cc409d86 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`, `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. + +* __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__: __Four (4) 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 and procedure 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. From 426c9eee0e1a3f703bd46dd236f2e418512a36ee Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:30:40 -0500 Subject: [PATCH 04/14] doc: Shorten line len in naming convention section STYLE_GUIDE.md: Shorten line length and use more semantic new-line breaks --- STYLE_GUIDE.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 8cc409d86..1a404f4b4 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -13,8 +13,12 @@ - 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` +- 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 From 93a686049d5577bfbdca07b1770310b848e0868c Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:32:08 -0500 Subject: [PATCH 05/14] doc: simplify white-space section of style guide Simplify the white-space section of STYLE_GUIDE.md and incorporate comments from Milan and Certik. --- STYLE_GUIDE.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 1a404f4b4..c1c03baeb 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -25,12 +25,10 @@ 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__: __Four (4) 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 +* The body of every Fortran construct should be indented by __4 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 From 7401a198219a6cda1299670ad9bc913595a83b20 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:45:21 -0500 Subject: [PATCH 06/14] style: consistently use asterisks for bullets --- STYLE_GUIDE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index c1c03baeb..a0a6fef35 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -11,14 +11,15 @@ ## 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 +* 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 +* 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` +* There should only ever be one `program` and `module` statement per file. ## Indentation & whitespace From 5eec482080c403e978f9e325d373fb89d77552f6 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:46:12 -0500 Subject: [PATCH 07/14] docs: Use @milancurcic's wording 4 naming section --- STYLE_GUIDE.md | 30 +++++------------------------- 1 file changed, 5 insertions(+), 25 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index a0a6fef35..ce3597564 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -33,31 +33,11 @@ focus on the semantics of the proposed changes rather than style and formatting. ## Variable and procedure 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. +* 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 From d91065d61fa53b9322b9bd82d3f50bcb417b8cf1 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:47:14 -0500 Subject: [PATCH 08/14] docs: simplify closing statement section * Recommend using names on end statements * Allow exceptions for very short constructs that can be reasonably assumed to be on one screen, within ~25 lines --- STYLE_GUIDE.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index ce3597564..b56836c81 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -42,8 +42,5 @@ focus on the semantics of the proposed changes rather than style and formatting. ## 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. +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. From f56de5a3086e2051bcf26fb7b1b7d6db753e8d67 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 16:55:35 -0500 Subject: [PATCH 09/14] docs: remove style-guide quote and add rationale The first paragraph with quote from Mike McQuaid was replaced with a brief paragraph. The new text aims to indicate why a style convention guide is useful and that it can be amended. --- STYLE_GUIDE.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index b56836c81..266a82c0a 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,13 +1,10 @@ # Fortran stdlib Style Guide -> [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 +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 poluting line endigs 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. ## File naming conventions From 3fade86d66029a415324b24fafb0506a1064c8d1 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 17:17:57 -0500 Subject: [PATCH 10/14] docs: use only standard Fortran Add @longb's suggestion to only use standardized language features and not obsolescent or deleted features and vendor extensions. --- STYLE_GUIDE.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 266a82c0a..9d653b086 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -6,6 +6,13 @@ This allows code review discussions to focus on semantics and substance rather t Consistent whitespace usage, and not poluting line endigs 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`. From 27bc1d7930f42e9ac60edf1cd9b96235136da428 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 17:20:14 -0500 Subject: [PATCH 11/14] docs: use punctuation consistently in bullets --- STYLE_GUIDE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 9d653b086..1512aca81 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -15,15 +15,15 @@ This style guide is a living document and proposed changes may be adopted after ## 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. +* 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`. + 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. + added E.g., `string_class.f90` and `tests/test_string_class.f90` -* There should only ever be one `program` and `module` statement per file. +* There should only ever be one `program` and `module` statement per file ## Indentation & whitespace @@ -31,7 +31,7 @@ By setting and following a convention for indentation and whitespace, code revie focus on the semantics of the proposed changes rather than style and formatting. * The body of every Fortran construct should be indented by __4 spaces__ -* Line length *should be limited to 80 characters* and __must not exceed 132__. +* 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 From e5b705bf73b021cdecaae24e963f56b364ca75a7 Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 17:22:00 -0500 Subject: [PATCH 12/14] docs: switch to two spaces of indentation Based on forming consensus in #3 --- .editorconfig | 6 +++--- STYLE_GUIDE.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.editorconfig b/.editorconfig index 0252cf222..b13434bad 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,14 +10,14 @@ root = true [*.{f90,F90}] indent_style = space -indent_size = 4 +indent_size = 2 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true [{CMakeLists.txt, *.cmake}] indent_style = space -indent_size = 4 +indent_size = 2 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true @@ -38,7 +38,7 @@ insert_final_newline = true [*.sh] indent_style = space -indent_size = 4 +indent_size = 2 trim_trailing_whitespace = true max_line_length = 132 insert_final_newline = true diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 1512aca81..143571e2c 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -30,7 +30,7 @@ This style guide is a living document and proposed changes may be adopted after 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 __4 spaces__ +* 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 From 7ba142d0b7c0714650eb5ce6047fd4711d0d693b Mon Sep 17 00:00:00 2001 From: Izaak Beekman Date: Sun, 29 Dec 2019 17:47:00 -0500 Subject: [PATCH 13/14] docs: remove redundant bullet Thanks to @ivan-pi for pointing this out. --- STYLE_GUIDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 143571e2c..60872ad68 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -23,7 +23,6 @@ This style guide is a living document and proposed changes may be adopted after * 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` -* There should only ever be one `program` and `module` statement per file ## Indentation & whitespace From ad52b9fbed59f4c338106a2a2d5ee17cbb5a6628 Mon Sep 17 00:00:00 2001 From: "Izaak \"Zaak\" Beekman" Date: Mon, 30 Dec 2019 20:59:59 -0500 Subject: [PATCH 14/14] Update STYLE_GUIDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ondřej Čertík --- STYLE_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 60872ad68..5860d6c02 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -3,7 +3,7 @@ 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 poluting line endigs with trailing white space makes `git diff`s considerably more legible. +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