From 3811558cfdaa76ec7885eda12881d467d23c3361 Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Mon, 9 Oct 2023 12:53:36 -0600 Subject: [PATCH 1/8] Flesh out editor settings and test clang-format 16 directives with VSCode. --- .clang-format | 3 +- doc/style.md | 79 +++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 69 insertions(+), 13 deletions(-) diff --git a/.clang-format b/.clang-format index c2e69bd..4aaecd0 100644 --- a/.clang-format +++ b/.clang-format @@ -1,4 +1,5 @@ --- +# clang-format version 16 Language: Cpp AccessModifierOffset: -2 AlignAfterOpenBracket: Align @@ -128,7 +129,7 @@ IndentRequiresClause: true IndentWidth: 4 IndentWrappedFunctionNames: false InsertBraces: false -InsertNewlineAtEOF: false +InsertNewlineAtEOF: true InsertTrailingCommas: None IntegerLiteralSeparator: Binary: 0 diff --git a/doc/style.md b/doc/style.md index 4d7da5a..d64b171 100644 --- a/doc/style.md +++ b/doc/style.md @@ -1,28 +1,34 @@ # C++ Conventions and Formatting Guidelines -This document is intended to summarize Big Ladder's approach to styling new C++ code, to maintain internal consistency between our original works. +This document is intended to summarize Big Ladder's approach to styling new C++ code, to maintain internal consistency between our original works. + +Note: This guide should not supersede the style used in third-party code bases - when contributing to an established project, always use the existing styles. For details of best practices in code craftsmanship, refer to the CPP Core Guidelines, actively maintained by the luminaries behind the C++ standard: [https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#main](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#main). -# Naming +# Naming ## File names -File names should be lowercase. +1. File names should be lowercase. -Interface (header) files should use the suffix “.h”. +1. Interface (header) files should use the suffix “.h”. -Implementation (code) files should use the suffix “.cpp”. +1. Implementation (code) files should use the suffix “.cpp”. -Use hyphens (“-”) to separate words in file names. +1. Use hyphens (“-”) to separate words in file names. ## Includes -Use angle brackets <> for external headers and quotes “” for internal headers. +Use angle brackets <> for external headers and quotes "" for internal headers. + +Example: + #include + #include "my_class_impl.h" ## Namespace names @@ -35,7 +41,7 @@ Example: ## Class names / Struct tags -Begin each word of the name with a capital letter. +Begin each word of the name with a capital letter. * If an acronym is used inside the class name, capitalize the letters of the acronym, as required, to convey meaning. @@ -51,7 +57,7 @@ NRELSolarDecathalon (vs. NrelSolarDecathalon) ## Variable names -Variable names should begin with a lower-case letter, using underscores to separate words. +Variable names should begin with a lower-case letter, using underscores to separate words. * Use descriptive variables names in preference to single letters (primarily for function or class scope). Abbreviations should be avoided. Code should be as self-documenting as possible. * Avoid coding the variable type into its name (as in “Hungarian” notation) @@ -75,20 +81,49 @@ Examples: ## Preprocessor symbols -In order to avoid naming conflicts between preprocessor directives and compiled code, symbols should always be all uppercase. +In order to avoid naming conflicts between preprocessor directives and compiled code, symbols and macros should always be all uppercase. + +Example: + + #define ABOUT_PI 3 ## Function names -Functions (free, friend, static, member functions, etc.) should begin with a lower-case letter, using underscores to separate words. +Functions (free, friend, static, member functions, etc.) should begin with a lower-case letter, using underscores to separate words. -* Functions in private class scope may begin a designated abbreviation for the class followed by an underscore +Example: + void member_function(int placeholder); ## Typedefs ## Comments +Use comments to *clarify intent* or *document unintiuitive behavior*. + +Use Doxygen-style comments that can be used to auto-generate class or library documentation. These should be in the header for public functions. + +Examples: +``` +/// @class Atheneum atheneum.h +/// @brief Interface for the Atheneum library + +class Atheneum { + ... +}; +``` + +``` + // -------------------------------------------------------------------- + /// @brief Add a table of data from which interpolated results + will be calculated. + /// @param value_vector Vector of length equal to the product + of dimension sizes. + /// @return Index in @c value_tables of the table just added + // -------------------------------------------------------------------- + std::size_t add_value_table(std::vector &value_vector); +``` # Formatting @@ -98,3 +133,23 @@ Prefer spaces to tab characters when indenting (set your text editor to replace The following clang-format list supports all (CPP-related) tags available in Clang 17, as listed in [https://clang.llvm.org/docs/ClangFormatStyleOptions.html](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) +## Editor settings + +1. Install clang-format 16+ in your path. + + * **VSCode:** Optionally, you can change the setting `"c_cpp:clang_format_path"` to point to your system clang-format (if it's not in the system path). Otherwise, + + >If not specified, and clang-format is available in the environment path, that is used. If not found in the environment path, the clang-format bundled with the [cpptools] extension will be used. + + (On Mac, it's located in `~/.vscode/extensions/ms-vscode.cpptools-1.17.5-darwin-x64/LLVM/bin/clang-format`) + +1. Set format-on-save (or on type, if preferred) + + * **VSCode:** Set `"editor.formatOnSave"` to format when you save your file, or `"editor.formatOnType"` to format as you type (triggered on the ; character). + +1. Trim trailing white space (not supported by clang-format; must be set in the IDE) + * **VSCode:** Set `"files.trimTrailingWhitespace"` : true + +1. Add extra line at the end of the file. (This is supported by clang-format 17 and higher with directive `InsertNewlineAtEOF: true`.) + +1. Line ending settings (Supported by clang-format directive `LineEnding: DeriveLF`.) From efd5379a9145ee2d725846e0b311f9cb92489e1d Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Mon, 9 Oct 2023 12:54:45 -0600 Subject: [PATCH 2/8] Fix version typo. --- doc/style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/style.md b/doc/style.md index d64b171..b88ca84 100644 --- a/doc/style.md +++ b/doc/style.md @@ -150,6 +150,6 @@ The following clang-format list supports all (CPP-related) tags available in Cla 1. Trim trailing white space (not supported by clang-format; must be set in the IDE) * **VSCode:** Set `"files.trimTrailingWhitespace"` : true -1. Add extra line at the end of the file. (This is supported by clang-format 17 and higher with directive `InsertNewlineAtEOF: true`.) +1. Add extra line at the end of the file. (This is supported by clang-format 16 and higher with directive `InsertNewlineAtEOF: true`.) 1. Line ending settings (Supported by clang-format directive `LineEnding: DeriveLF`.) From 3758bc5527826cc65acc6fb7deb17c2fe6505ea8 Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Tue, 10 Oct 2023 19:22:36 -0600 Subject: [PATCH 3/8] Add name guidelines. --- doc/style.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/style.md b/doc/style.md index b88ca84..b983bd6 100644 --- a/doc/style.md +++ b/doc/style.md @@ -59,16 +59,21 @@ NRELSolarDecathalon (vs. NrelSolarDecathalon) Variable names should begin with a lower-case letter, using underscores to separate words. -* Use descriptive variables names in preference to single letters (primarily for function or class scope). Abbreviations should be avoided. Code should be as self-documenting as possible. -* Avoid coding the variable type into its name (as in “Hungarian” notation) +* Do use names that are + * descriptive + * intention-revealing + * self-documenting + * pronounceable -Local variables: +* Avoid + * coding the variable type into its name (as in “Hungarian” notation) + * abbreviations / single letters + * difference without distinction (i.e. var-latest vs. var-final) + * names that are cutesey or inside-joke-y - int local_variable; +Class member variables should not use any prefix or suffix to denote type, scope, or constness. -Variables of classes should not use any prefix or suffix to denote type, scope, or constness. - -Append `_in` to argument variable names to explicitly prevent shadowing of arguments with names similar to member variable names. +If function input arguments might shadow member or local variable names used inside the function, append `_in` to the argument variable names to explicitly prevent shadowing. ## Enumeration names From 5ee68c33b55e6fbe4fd6e503922755c46bc83e71 Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Thu, 12 Oct 2023 10:36:53 -0600 Subject: [PATCH 4/8] Fix PR recommendations. --- doc/style.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/style.md b/doc/style.md index b983bd6..efbe29d 100644 --- a/doc/style.md +++ b/doc/style.md @@ -9,6 +9,19 @@ For details of best practices in code craftsmanship, refer to the CPP Core Guide # Naming +## General guidelines + +* Do use names that are + * descriptive + * intention-revealing + * self-documenting + * pronounceable + +* Avoid + * coding the variable type into its name (as in “Hungarian” notation) + * abbreviations / single letters + * difference without distinction (i.e. var-latest vs. var-final) + * names that are cutesey or inside-joke-y ## File names @@ -21,14 +34,14 @@ For details of best practices in code craftsmanship, refer to the CPP Core Guide 1. Use hyphens (“-”) to separate words in file names. -## Includes +### Includes Use angle brackets <> for external headers and quotes "" for internal headers. Example: #include - #include "my_class_impl.h" + #include "my-class-impl.h" ## Namespace names @@ -38,7 +51,6 @@ Example: namespace bigladder {} - ## Class names / Struct tags Begin each word of the name with a capital letter. @@ -59,23 +71,10 @@ NRELSolarDecathalon (vs. NrelSolarDecathalon) Variable names should begin with a lower-case letter, using underscores to separate words. -* Do use names that are - * descriptive - * intention-revealing - * self-documenting - * pronounceable - -* Avoid - * coding the variable type into its name (as in “Hungarian” notation) - * abbreviations / single letters - * difference without distinction (i.e. var-latest vs. var-final) - * names that are cutesey or inside-joke-y - Class member variables should not use any prefix or suffix to denote type, scope, or constness. If function input arguments might shadow member or local variable names used inside the function, append `_in` to the argument variable names to explicitly prevent shadowing. - ## Enumeration names If an enumeration has a tag or enum class name, it follows the same convention as classes: begin with a capital letter and then capitalize any words within the name. The individual enumerants should be lower-case, underscore-separated. From 8824c0157a5b98d8fa7905841a70a1d2a4da3d6c Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Thu, 12 Oct 2023 12:52:55 -0600 Subject: [PATCH 5/8] Edit with comments from code review. --- doc/style.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/style.md b/doc/style.md index efbe29d..3b14c45 100644 --- a/doc/style.md +++ b/doc/style.md @@ -21,7 +21,9 @@ For details of best practices in code craftsmanship, refer to the CPP Core Guide * coding the variable type into its name (as in “Hungarian” notation) * abbreviations / single letters * difference without distinction (i.e. var-latest vs. var-final) - * names that are cutesey or inside-joke-y + * names that are too colloquial, cutesey or inside-joke-y + +* Be judicious about adding unit descriptors to numeric variables. ## File names @@ -41,7 +43,7 @@ Use angle brackets <> for external headers and quotes "" for internal headers Example: #include - #include "my-class-impl.h" + #include "class-internals.h" ## Namespace names @@ -85,7 +87,7 @@ Examples: ## Preprocessor symbols -In order to avoid naming conflicts between preprocessor directives and compiled code, symbols and macros should always be all uppercase. +In order to avoid naming conflicts between preprocessor directives and compiled code, symbols and macros should always be all uppercase. Symbols and macros (used sparingly) should also have descriptive and self-documenting names. Example: @@ -97,7 +99,7 @@ Functions (free, friend, static, member functions, etc.) should begin with a low Example: - void member_function(int placeholder); + void use_primary_algorithm(int placeholder); ## Typedefs @@ -139,6 +141,8 @@ The following clang-format list supports all (CPP-related) tags available in Cla ## Editor settings +1. The common IDEs (Visual Studio, VS Code, CLion) can utilize text-coloring to highlight syntax or scope. We typically rely on this highlighting to differentiate member vs local variables, for example. + 1. Install clang-format 16+ in your path. * **VSCode:** Optionally, you can change the setting `"c_cpp:clang_format_path"` to point to your system clang-format (if it's not in the system path). Otherwise, From 63eef9b00bca6dadd32ca9f17762c8ea9df6ac72 Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Mon, 23 Oct 2023 12:17:58 -0600 Subject: [PATCH 6/8] Fix brace breaking to Allman style. --- .clang-format | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.clang-format b/.clang-format index 4aaecd0..3c21891 100644 --- a/.clang-format +++ b/.clang-format @@ -81,7 +81,7 @@ BreakAfterJavaFieldAnnotations: false BreakArrays: true BreakBeforeBinaryOperators: None BreakBeforeConceptDeclarations: Always -BreakBeforeBraces: Stroustrup +BreakBeforeBraces: Allman BreakBeforeInlineASMColon: OnlyMultiline BreakBeforeTernaryOperators: true BreakConstructorInitializers: BeforeComma From 0da3d8bcfacd383dcda0aaefdc14cd362bc9b43b Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Mon, 23 Oct 2023 12:18:56 -0600 Subject: [PATCH 7/8] Format braces in source files. --- src/atheneum-private.h | 6 ++++-- src/atheneum.cpp | 3 ++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/atheneum-private.h b/src/atheneum-private.h index 9abf4b3..ec49b7f 100644 --- a/src/atheneum-private.h +++ b/src/atheneum-private.h @@ -3,9 +3,11 @@ #pragma once -namespace Atheneum { +namespace Atheneum +{ -class AtheneumPrivate { +class AtheneumPrivate +{ public: AtheneumPrivate(); int answer(); diff --git a/src/atheneum.cpp b/src/atheneum.cpp index ca2c5a1..10bcd6b 100644 --- a/src/atheneum.cpp +++ b/src/atheneum.cpp @@ -9,7 +9,8 @@ #include "atheneum-private.h" -namespace Atheneum { +namespace Atheneum +{ Atheneum::Atheneum() { atheneum = std::unique_ptr(new AtheneumPrivate()); } From e2556339075c7bd168903fa37f5dca570ad66e2e Mon Sep 17 00:00:00 2001 From: Tanaya Mankad Date: Mon, 23 Oct 2023 12:21:08 -0600 Subject: [PATCH 8/8] Format leftover file. --- include/atheneum/atheneum.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/include/atheneum/atheneum.h b/include/atheneum/atheneum.h index 0383018..df803f9 100644 --- a/include/atheneum/atheneum.h +++ b/include/atheneum/atheneum.h @@ -7,11 +7,13 @@ #include #include -namespace Atheneum { +namespace Atheneum +{ class AtheneumPrivate; -class Atheneum { +class Atheneum +{ public: Atheneum(); ~Atheneum();