From b67d400f607b92b717a65a49af72cb8ae3186794 Mon Sep 17 00:00:00 2001 From: TheKodeToad Date: Wed, 6 Nov 2024 15:56:10 +0000 Subject: [PATCH 1/2] Update formatting guidelines Signed-off-by: TheKodeToad --- CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 072916772..d76f992eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,16 +2,54 @@ ## Code formatting -Try to follow the existing formatting. -If there is no existing formatting, you may use `clang-format` with our included `.clang-format` configuration. +All files are formatted with `clang-format` using the configuration in `.clang-format`. Ensure it is run on changed files before committing! -In general, in order of importance: +We have no tool for enforcing names but please follow the following conventions for C++: +- Class and type names should be formatted as `PascalCase`: `MyClass`. +- Private, non-`static const` class data members should be formatted as `camelCase` prefixed with `m_`: `m_myCounter`. +- Public, non-`static const` should be the same but without the prefix: `dateOfBirth`. +- Class function members should be formatted as `camelCase` without a prefix: `incrementCounter`. +- Non-`const` global variables should be formatted as `camelCase` without a prefix: `globalData`. And, of course, should be avoided where possible. +- `const` global variables, `static const` class data members, macros, and enum constants should be formatted as `SCREAMING_SNAKE_CASE`: `LIGHT_GRAY`. +- Avoid inventing acronyms or abbreviations especially for a name of multiple words - like `tp` for `texturePack`. -- Make sure your IDE is not messing up line endings or whitespace and avoid using linters. -- Prefer readability over dogma. -- Keep to the existing formatting. -- Indent with 4 space unless it's in a submodule. -- Keep lists (of arguments, parameters, initializers...) as lists, not paragraphs. It should either read from top to bottom, or left to right. Not both. +Here is what these conventions with the formatting configuration look like: + +```c++ +#define AWESOMENESS 10 + +constexpr double PI = 3.14159; + +enum class PizzaToppings { HAM_AND_PINEAPPLE, OREO_AND_KETCHUP }; + +struct Person { + QString name; + QDateTime dateOfBirth; + + long daysOld() const { return dateOfBirth.daysTo(QDateTime::currentDateTime()); } +}; + +class ImportantClass { + public: + void incrementCounter() + { + if (m_counter + 1 > MAX_COUNTER_VALUE) + throw std::runtime_error("Counter has reached limit!"); + + ++m_counter; + } + + int counter() const { return m_counter; } + + private: + static constexpr int MAX_COUNTER_VALUE = 100; + int m_counter; +}; + +ImportantClass importantClassInstance; +``` + +If you see any names which do not follow these conventions, it is preferred that you leave them be - renames increase the number of changes therefore make reviewing harder and make your PR more prone to conflicts. However, if you're refactoring a whole class anyway, it's fine. ## Signing your work From 8ecc21c09371914fc8cc44e1596ced949f0cbb39 Mon Sep 17 00:00:00 2001 From: TheKodeToad Date: Wed, 6 Nov 2024 22:12:22 +0000 Subject: [PATCH 2/2] Make Ryex's suggested change Signed-off-by: TheKodeToad --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d76f992eb..f016391d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,11 +6,13 @@ All files are formatted with `clang-format` using the configuration in `.clang-f We have no tool for enforcing names but please follow the following conventions for C++: - Class and type names should be formatted as `PascalCase`: `MyClass`. -- Private, non-`static const` class data members should be formatted as `camelCase` prefixed with `m_`: `m_myCounter`. -- Public, non-`static const` should be the same but without the prefix: `dateOfBirth`. +- Private or protected class data members should be formatted as `camelCase` prefixed with `m_`: `m_myCounter`. +- Private or protected `static` class data members should be formatted as `camelCase` prefixed with `s_`: `s_instance`. +- Public class data members should be formatted as `camelCase` without the prefix: `dateOfBirth`. +- Public, private or protected `static const` class data members should be formatted as `SCREAMING_SNAKE_CASE`: `MAX_VALUE`. - Class function members should be formatted as `camelCase` without a prefix: `incrementCounter`. - Non-`const` global variables should be formatted as `camelCase` without a prefix: `globalData`. And, of course, should be avoided where possible. -- `const` global variables, `static const` class data members, macros, and enum constants should be formatted as `SCREAMING_SNAKE_CASE`: `LIGHT_GRAY`. +- `const` global variables, macros, and enum constants should be formatted as `SCREAMING_SNAKE_CASE`: `LIGHT_GRAY`. - Avoid inventing acronyms or abbreviations especially for a name of multiple words - like `tp` for `texturePack`. Here is what these conventions with the formatting configuration look like: