diff options
Diffstat (limited to 'contributing.md')
| -rw-r--r-- | contributing.md | 55 |
1 files changed, 53 insertions, 2 deletions
diff --git a/contributing.md b/contributing.md index 832667d..a6e5074 100644 --- a/contributing.md +++ b/contributing.md @@ -14,14 +14,65 @@ - TODO: tagging / versions + # Code style - ASCII only +- Class names are always singular +- Explanatory comments are placed above the line(s) they are explaining +- Source files should only contain comments that plainly state what the code is + supposed to do +- Explanatory comments in headers may be used to clarify implementation design + decisions - Formatting nitty-gritty is handled by clang-format/clang-tidy (run `make format` in the root folder of this repository to format all sources files) +- Header includes are split into paragraphs separated by a blank line. The + order is: + 1. system headers (using `<`brackets`>`) + 2. relative headers NOT in the same folder as the current file + 3. relative headers in the same folder as the current file - When using libraries of which the header include order is important, make sure to separate the include statements using a blank line (clang-format may sort include statements, but does not sort across empty lines). +- All engine-related code is implemented under the `crepe` namespace, + user-facing APIs under `crepe::api` (the folder structure should also reflect + this). +- `using namespace` may not be used in header files, only in source files. +- Do not (indirectly) include private *dependency* headers in API header files, + as these are no longer accessible when the engine is installed +- Getter and setter functions are appropriately prefixed with `get_` and + `set_`. +- Doxygen commands are used with a backslash instead of an at-sign (i.e. + `\brief` instead of `@brief`) +- A singleton's instance is always accessed using a getter function that + instantiates its own class as a static variable within the getter function + scope, instead of storing the instance as a member variable directly: + + ```cpp + class Bad { + static Bad instance; + Bad & get_instance() { return instance; } + }; + + class Good { + Good & get_instance() { + static Good instance; + return instance; + } + }; + ``` +- Member variable default values should be directly defined in the class + declaration instead of using the constructor. +- Header files declare either a single class or symbols within a single + namespace. +- Only use member initializer lists for non-trivial types. +- C++-style structs should define default values for all non-trivial fields. +- Declare incomplete classes instead of including the relevant header where + possible (i.e. if you only need a reference or pointer type). +- Template functions are only declared in a `.h` header, and defined in a + matching `.hpp` header. +- Where possible, end (initializer) lists with a trailing comma (e.g. with + structs, enums) ## CMakeLists specific @@ -38,6 +89,6 @@ - External libraries should be included as Git submodules under the `lib/` subdirectory -- When adding new submodules, make sure to manually set the `branch` and - `shallow` options in the [.gitmodules](./.gitmodules) file +- When adding new submodules, please set the `shallow` option to `true` in the + [.gitmodules](./.gitmodules) file |