From 05d67405a9908eee3815a7378ca58336fdb07d74 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 16:26:11 -0700 Subject: [PATCH 1/7] Add some style guide verbiage * Headers * C/C++ standards * A few misc other things --- STYLEGUIDE.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index c1695e15..37ee0151 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -4,17 +4,38 @@ ### Organization ### Naming +* Use hyphens instead of underscores in filenames + ## Formatting +* Code must meet the requirements of our options to `clang-format` + ## Naming Conventions ## Comments and Documentation ## Header Guidelines +* Headers should follow [include-what-you-use](https://include-what-you-use.org/) guidelines +* Use `#pragma once` instead of include guards +* Place local headers (quoted) ahead of system headers (brackets), with each block in alphabetical order +* Public headers MUST have Doxygen markup for all public symbols +* Private headers should have Doxygen markup flagged with `@internal` + ## Language Features and Idioms -### C++ -### C + +### C/C++ + +* C++17 and C11 are supported +* Use modern C++ idioms +* Do not use GNU extensions +* Code should be platform-independent + +### Shell scripts + +* All shell scripts should be run through [shellcheck](https://www.shellcheck.net/) and report no issues +* Use `#!/usr/bin/env bash` as a platform-independent shebang line +* bash-isms are allowed, within reason ## Error Handling From c32c24156eba2b808e15a2e8ed1a7056d38875da Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 16:37:47 -0700 Subject: [PATCH 2/7] Added some testing information --- STYLEGUIDE.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 37ee0151..b4f35cad 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -4,7 +4,7 @@ ### Organization ### Naming -* Use hyphens instead of underscores in filenames +* Use hyphens instead of underscores in file and directory names ## Formatting @@ -41,5 +41,10 @@ ## Testing Conventions +* All new functionality introduced MUST include tests of the feature + * This chould include unit tests, system tests, and integration tests + * These tests MUST be automatable +* Bugfixes MUST include a proof-of-concept test that fails before the fix and passes after + ## Tooling and Enforcement clang-tidy, formatter, etc. From ed832316ddbaca76156218cd815a844d5f85f5de Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 16:38:59 -0700 Subject: [PATCH 3/7] Fix trailing space --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index b4f35cad..52932e54 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -35,7 +35,7 @@ * All shell scripts should be run through [shellcheck](https://www.shellcheck.net/) and report no issues * Use `#!/usr/bin/env bash` as a platform-independent shebang line -* bash-isms are allowed, within reason +* bash-isms are allowed, within reason ## Error Handling From b43ab98b0a76b88d87b15ab4741a0114ea0f8d5d Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 16:40:15 -0700 Subject: [PATCH 4/7] Fix typo --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 52932e54..fff4bfd8 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -42,7 +42,7 @@ ## Testing Conventions * All new functionality introduced MUST include tests of the feature - * This chould include unit tests, system tests, and integration tests + * This could include unit tests, system tests, and integration tests * These tests MUST be automatable * Bugfixes MUST include a proof-of-concept test that fails before the fix and passes after From afb82e03eca10c45df634723976e869612e90583 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 16:59:33 -0700 Subject: [PATCH 5/7] Fix caps in ShellCheck --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index fff4bfd8..701a46d7 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -33,7 +33,7 @@ ### Shell scripts -* All shell scripts should be run through [shellcheck](https://www.shellcheck.net/) and report no issues +* All shell scripts should be run through [ShellCheck](https://www.shellcheck.net/) and report no issues * Use `#!/usr/bin/env bash` as a platform-independent shebang line * bash-isms are allowed, within reason From 52e19906064265963a4944818aa81a1106963102 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 18 Nov 2025 17:56:37 -0700 Subject: [PATCH 6/7] Add a blurb about CMake standards --- STYLEGUIDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 701a46d7..96f6a39b 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -24,6 +24,10 @@ ## Language Features and Idioms +### CMake +* We use CMake 3.x (see the root `CMakeLists.txt` for the specific version) and have not moved to 4.x yet +* Use modern CMake (e.g.; 3.x) paradigms and avoid "legacy CMake" + ### C/C++ * C++17 and C11 are supported From bf80bbe4e7e3506c729f392d2f56afb9968cd9fa Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 19 Nov 2025 04:46:15 -0700 Subject: [PATCH 7/7] Fix typo --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 96f6a39b..6cd2212d 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -26,7 +26,7 @@ ### CMake * We use CMake 3.x (see the root `CMakeLists.txt` for the specific version) and have not moved to 4.x yet -* Use modern CMake (e.g.; 3.x) paradigms and avoid "legacy CMake" +* Use modern CMake (e.g., 3.x) paradigms and avoid "legacy CMake" ### C/C++