diff options
Diffstat (limited to 'contributing.md')
| -rw-r--r-- | contributing.md | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/contributing.md b/contributing.md index eec5bc0..5cbad61 100644 --- a/contributing.md +++ b/contributing.md @@ -14,6 +14,7 @@ - TODO: tagging / versions + # Code style - ASCII only @@ -22,6 +23,215 @@ - 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; + }; +} +``` +- 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. +``` ## CMakeLists specific @@ -30,6 +240,11 @@ resolving merge conflicts when multiple sources were added by different people to the same CMakeLists.txt easier. +## Doxygen style + +- [a C-style doxygen example](https://www.cs.cmu.edu/~410/doc/doxygen.html) + + # Documentation - All documentation is written in U.S. English |