aboutsummaryrefslogtreecommitdiff
path: root/contributing.md
diff options
context:
space:
mode:
Diffstat (limited to 'contributing.md')
-rw-r--r--contributing.md242
1 files changed, 35 insertions, 207 deletions
diff --git a/contributing.md b/contributing.md
index 5cbad61..379494d 100644
--- a/contributing.md
+++ b/contributing.md
@@ -18,220 +18,48 @@
# 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)
- 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).
-- [Cpp practices](https://lefticus.gitbooks.io/cpp-best-practices/content/)
-- [C++ core guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)
-- [Google c++ style](https://google.github.io/styleguide/cppguide.html)
-
-
-- .h basic code style with doxygen
-```cpp
-// code-style-example/style.cpp
-/*! @file MyClass.h */
-
-#ifndef MYPROJECT_MYCLASS_HPP
-#define MYPROJECT_MYCLASS_HPP
-
-/**
- * @brief example class
- */
-class MyClass {
-
-public:
- /**
- * @brief example constructor
- *
- * @param[integer] t_value example first argument
- */
- MyClass(int t_value);
-
- /**
- * @brief constructor example
- *
- */
- MyClass();
-
- /**
- * @brief deconstuctor example
- *
- */
- ~MyClass();
-
- /**
- * @brief setter example with correct const implementation
- *
- * @param[const integer] t_value first argument
- */
- void set_value(const int t_value);
-
- /**
- * @brief getter example with correct const implementation
- *
- * @return const integer
- */
- const int get_value() const;
-
- /**
- * @brief increment member m_value
- *
- */
- void increment();
-
-private:
- /**
- * @m_value basic member example
- */
- int m_value;
-};
-
-#endif
-```
-
-- .cpp basic code style
-```cpp
-// code-style-example/style.cpp
-
-#include "style.h"
-
-MyClass::MyClass(int t_value) : m_value(t_value) {}
-
-MyClass::MyClass() { m_value = 0; }
-
-MyClass::~MyClass() {}
-
-const int MyClass::get_value() const { return m_value; }
-
-void MyClass::set_value(const int t_value) { m_value = t_value; }
-
-void MyClass::increment() { m_value += 1; }
-```
-
-- when to use references
-
--- If the input parameter in the function cannot accept a nullptr
-```cpp
-void foo::function(const std::string& name){};
-```
--- Use a reference when you know that the object will exist for the lifetime of the reference and when nullability is not a concern.
-```cpp
-int x = 10;
-int& ref = x;
-ref = 20;
-```
-
--- If a function should return a reference to an object that exists elsewhere (such as a member of a class or an element in a container), you can return a reference.
-```cpp
-container& get_element(std::vector<container>& vec, size_t index){
- return vec[index];
-}
-```
-- When to use pointers
-
--- Use pointers when dealing with dynamic memory
-```cpp
-int* ptr = new int(5);
-delete ptr;
-```
-
--- Pointers can be nullptr, allowing them to represent "no object." Use pointers when you need to express optional ownership or reference.
-```cpp
-void foo::function(int* ptr){
- if(ptr){
- // ptr is not null
- }
-}
-```
-
--- When dealing with polymorphism.
-```cpp
-class Base {};
-class Derived : public Base {};
-
-Base* obj = new Derived();
-obj->function();
-```
-
-
-- Do not use auto
-
--- Instead of doing this
-```cpp
-auto s = "Hello";
-auto x = "42"s;
-auto x = 42;
-auto x = 42.f;
-```
--- Do this.
-```cpp
-std::string s = "Hello";
-std::string x = "42"s;
-int x = 42;
-float x = 42.f;
-```
-- Do not define constants as define but instead directly declare it.
--- This is wrong.
-```cpp
-#define PI 3.14159;
-```
-
--- Do this.
-```cpp
-namespace my_project {
- class Constants {
- public:
- static constexpr double PI = 3.14159;
+- 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; }
};
-}
-```
-- Use enum class instead of using enum only to prevent bugs
-```cpp
-void Print_color(int color);
-
-enum Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
-enum Product_info { red = 0, purple = 1, blue = 2 };
-
-Web_color webby = Web_color::blue;
-
-// Clearly at least one of these calls is buggy.
-Print_color(webby);
-Print_color(Product_info::blue);
-```
-- Instead use an enum class:
-```cpp
-
-void Print_color(int color);
-enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
-enum class Product_info { red = 0, purple = 1, blue = 2 };
-
-Web_color webby = Web_color::blue;
-Print_color(webby); // Error: cannot convert Web_color to int.
-Print_color(Product_info::red); // Error: cannot convert Product_info to int.
-
-```
-
-- Think about using size_t instead of using int for preventing processor mismatching. This might prevent a bug in the future.
-```cpp
-std::size_t i = 0; // use this instead of using a int
-double x = 0.0;
-```
-- comment style guide, you can use TODO:, FIXME:, NOTE:, or HACK: as admonitions when needed.
-
--- Bad example
-```cpp
-// Draw loading screen.
-draw_load_screen();
-```
--- Better
-```cpp
-// Compute the first 10,000 decimals of Pi.
-// FIXME: Don't crash when computing the 1,337th decimal due to `increment`
-// being negative.
-```
+ 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.
## CMakeLists specific