From 5f75bdbf3d38c94baeae52f4c4889f147ec6885e Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 5 Nov 2024 15:34:31 +0100 Subject: move systems + update contributing.md --- contributing.md | 156 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 92 insertions(+), 64 deletions(-) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 38a83fd..35d777d 100644 --- a/contributing.md +++ b/contributing.md @@ -1,11 +1,15 @@ -# Contributing new code +This document contains +
+examples + +that you can click on to open them. +
+ +# Git - Please do the following *before* sending a pull request: - Merge upstream code (if any) back into your own branch - Run formatters/linters - -# Git - - Push as often as possible - Development is done on separate branches, these follow a pattern of `name/feature` (i.e. `loek/dll-so-poc` or `jaro/class2`) @@ -17,8 +21,9 @@ - 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) -- ASCII only -
GoodBad
+-
+ ASCII only +
GoodBad
```cpp // crepe startup message @@ -30,9 +35,10 @@ // crêpe startup message std::string message = "こんにちは世界"; ``` -
-- Class names are always singular -
GoodBad
+
+-
+ Class names are always singular +
GoodBad
```cpp class Foo {}; @@ -42,7 +48,7 @@ ```cpp class Cars {}; ``` -
+
- Source files contain the following types of comments: - What is the code supposed to do (optional) - Implementation details (if applicable) @@ -50,8 +56,9 @@ - Usage documentation (required) - Implementation details (if they affect the header) - Design/data structure decisions (if applicable) -- Comments are placed *above* the line(s) they are explaining -
GoodBad
+-
+ Comments are placed *above* the line(s) they are explaining +
GoodBad
```cpp int add(int a, int b) { @@ -68,7 +75,7 @@ return out; } ``` -
+
- Header includes are split into paragraphs separated by a blank line. The order is: 1. system headers (using `<`brackets`>`) @@ -80,6 +87,7 @@ > sure to separate the include statements using a blank line (clang-format > may sort include statements, but does not sort across empty lines). +
Example
GoodBad
```cpp @@ -100,9 +108,10 @@ #include #include "api/Sprite.h" ``` -
-- `using namespace` may not be used in header files, only in source files. -
GoodBad
+
+-
+ using namespace may not be used in header files, only in source files. +
GoodBad
example.h: ```cpp @@ -134,10 +143,12 @@ template T foo(); ``` -
+
-- Getter and setter functions are appropriately prefixed with `get_` and `set_`. -
GoodBad
+-
+ Getter and setter functions are appropriately prefixed with get_ + and set_. +
GoodBad
```cpp class Foo { @@ -160,12 +171,12 @@ int speed; }; ``` -
- -- A singleton's instance is always accessed using a getter function that +
+-
+ 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: -
GoodBad
+ scope, instead of storing the instance as a member variable directly. +
GoodBad
```cpp class Foo { @@ -186,11 +197,11 @@ }; ``` -
- -- Member variable default values should be directly defined in the class/struct +
+-
+ Member variable default values should be directly defined in the class/struct declaration instead of using the constructor. -
GoodBad
+
GoodBad
```cpp class Foo { @@ -206,28 +217,39 @@ int speed; }; ``` -
- +
- Use of the `auto` type is *not* allowed, with the following exceptions: - - When naming the item type in a range-based for loop: - + -
+ When naming the item type in a range-based for loop + + ```cpp for (auto & item : foo()) { // ... } ``` - - When calling template factory methods that explicitly name the return type +
+ -
+ When calling template factory methods that explicitly name the return type in the function call signature + + ```cpp auto ptr = make_unique(); ``` - - When fetching a singleton instance +
+ -
+ When fetching a singleton instance + + ```cpp auto & mgr = crepe::api::Config::get_instance(); ``` +
-- Only use member initializer lists for non-trivial types. -
GoodBad
+-
+ Only use member initializer lists for non-trivial types. +
GoodBad
```cpp class Foo { @@ -248,10 +270,10 @@ int bar; }; ``` -
- -- C++-style structs should define default values for all non-trivial fields. -
GoodBad
+
+-
+ C++-style structs should define default values for all non-trivial fields. +
GoodBad
```cpp struct Foo { @@ -267,11 +289,11 @@ std::string baz; }; ``` -
- -- Declare incomplete classes instead of including the relevant header where +
+-
+ Declare incomplete classes instead of including the relevant header where possible (i.e. if you only need a reference or raw pointer). -
GoodBad
+
GoodBad
```cpp class Bar; @@ -288,11 +310,11 @@ Bar & bar; }; ``` -
- -- Template functions are only *declared* in a `.h` header, and *defined* in a - matching `.hpp` header. -
GoodBad
+
+-
+ Template functions are only declared in a .h header, and + defined in a matching .hpp header. +
GoodBad
add.h: ```cpp @@ -320,11 +342,11 @@ return a + b; } ``` -
- -- Where possible, end (initializer) lists with a trailing comma (e.g. with +
+-
+ Where possible, end (initializer) lists with a trailing comma (e.g. with structs, enums) -
GoodBad
+
GoodBad
```cpp enum Color { @@ -343,9 +365,10 @@ Blue }; ``` -
-- `#pragma` should be used instead of include guards -
GoodBad
+
+-
+ #pragma should be used instead of include guards +
GoodBad
```cpp #pragma once @@ -362,7 +385,7 @@ #endif ``` -
+
## CMakeLists-specific @@ -373,20 +396,25 @@ # Structure -- All engine-related code is implemented under the `crepe` namespace, - user-facing APIs under `crepe::api` (the folder structure should also reflect - this). +- Files are placed in the appropriate directory: + |Path|Purpose| + |-|-| + |`crepe/`|Auxiliary, managers| + |`crepe/api/`|User-facing APIs| + |`crepe/util/`|Standalone utilities and helper functions| + |`crepe/system/`|(ECS) system classes| - Do not (indirectly) include private *dependency* headers in API header files, as these are no longer accessible when the engine is installed +- All code is implemented under the `crepe` namespace. - Header files declare either a single class or symbols within a single namespace. -- TODO: folder structure # Documentation - All documentation is written in U.S. English -- Doxygen commands are used with a backslash instead of an at-sign. -
GoodBad
+-
+ Doxygen commands are used with a backslash instead of an at-sign. +
GoodBad
```cpp /** @@ -406,7 +434,7 @@ */ void foo(); ``` -
+
# Libraries -- cgit v1.2.3