update contributing.md

1 files changed, 259 insertions, 208 deletions

diff --git a/contributing.md b/contributing.md
index 4c347bb..38a83fd 100644
--- a/contributing.md
+++ b/contributing.md
@@ -11,351 +11,402 @@
   `name/feature` (i.e. `loek/dll-so-poc` or `jaro/class2`)
 - The master branch is considered stable, and should always contain a
   working/compiling version of the project
-
 - TODO: tagging / versions
 
-
 # Code style
 
+- 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
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
+  // crepe startup message
   std::string message = "Hello, world!";
-  
-  // Bad
-  std::string message = "こんにちは世界";
   ```
+  </td><td>
 
+  ```cpp
+  // crêpe startup message
+  std::string message = "こんにちは世界";
+  ```
+  </td></tr></table>
 - Class names are always singular
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  class Car {};
-  
-  // Bad
-  class Cars {};
+  class Foo {};
   ```
-
-- Explanatory comments are placed above the line(s) they are explaining
+  </td><td>
 
   ```cpp
-  // Good
-  // This function adds two numbers
-  int add(int a, int b) {
-      return a + b;
-  }
-  
-  // Bad
-  int add(int a, int b) {
-      return a + b; // This function adds two numbers
-  }
+  class Cars {};
   ```
-
-- Source files should only contain comments that plainly state what the code is supposed to do
+  </td></tr></table>
+- Source files contain the following types of comments:
+  - What is the code supposed to do (optional)
+  - Implementation details (if applicable)
+- Header files contain the following types of comments:
+  - 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
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  // Initialize the engine
-  engine.init();
-  
-  // Bad
-  // Initialize the engine with default settings and prepare it for running
-  engine.init();
+  int add(int a, int b) {
+    // add numbers
+    int out = a + b;
+    return out;
+  }
   ```
-
-- Explanatory comments in headers may be used to clarify implementation design decisions
+  </td><td>
 
   ```cpp
-  // Good
-  // This class handles the rendering process
-  class Renderer {
-      // This method initializes the rendering context
-      void init_context();
-  };
-  
-  // Bad
-  class Renderer {
-      void init_context(); // This method initializes the rendering context
-  };
+  int add(int a, int b) {
+    int out = a + b; // add numbers
+    return out;
+  }
   ```
-
-- 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:
+  </td></tr></table>
+- 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
 
-  ```cpp
-  // Good
-  #include <iostream>
-  
-  #include "utils/helper.h"
-  
-  #include "main.h"
-  
-  // Bad
-  #include "main.h"
-  #include <iostream>
-  #include "utils/helper.h"
-  ```
+  > [!NOTE]
+  > 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).
 
-- 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).
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
+  #include <SDL2/SDL.h>
   #include <iostream>
-  
-  #include <boost/algorithm/string.hpp>
-  
-  // Bad
-  #include <iostream>
-  #include <boost/algorithm/string.hpp>
-  ```
 
-- All engine-related code is implemented under the `crepe` namespace, user-facing APIs under `crepe::api` (the folder structure should also reflect this).
+  #include "api/Sprite.h"
+  #include "util/log.h"
 
+  #include "SDLContext.h"
+  ```
+  </td><td>
 
+  ```cpp
+  #include <SDL2/SDL.h>
+  #include "SDLContext.h"
+  #include "util/log.h"
+  #include <iostream>
+  #include "api/Sprite.h"
+  ```
+  </td></tr></table>
 - `using namespace` may not be used in header files, only in source files.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
+  example.h:
   ```cpp
-  // Good
-  // header.h
   namespace crepe {
-      void init();
+  void foo();
   }
+  ```
   
-  // source.cpp
-  #include "header.h"
-  using namespace crepe;
-  void init() {}
-  
-  // Bad
-  // header.h
+  example.cpp:
+  ```cpp
+  #include "example.h"
   using namespace crepe;
-  void init();
+  void foo() {}
   ```
+  </td><td>
 
-- Do not (indirectly) include private *dependency* headers in API header files, as these are no longer accessible when the engine is installed
-
+  example.h:
   ```cpp
-  // Good
-  // api.h
-  namespace crepe::api {
-      void start();
+  namespace crepe {
+  template <typename T>
+  T foo();
   }
+  ```
   
-  // Bad
-  // api.h
-  #include "private_dependency.h"
-  namespace crepe::api {
-      void start();
-  }
+  example.hpp:
+  ```cpp
+  #include "example.h"
+  using namespace crepe;
+  template <typename T>
+  T foo();
   ```
+  </td></tr></table>
 
 - Getter and setter functions are appropriately prefixed with `get_` and `set_`.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  class Car {
+  class Foo {
   public:
-      int get_speed() const;
-      void set_speed(int speed);
+    int get_speed() const;
+    void set_speed(int speed);
   private:
-      int speed;
+    int speed;
   };
   
-  // Bad
-  class Car {
+  ```
+  </td><td>
+
+  ```cpp
+  class Foo {
   public:
-      int speed() const;
-      void speed(int speed);
+    int speed() const;
+    void set_speed(int speed);
   private:
-      int speed;
+    int speed;
   };
   ```
+  </td></tr></table>
 
-- 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:
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  /// \brief This function adds two numbers
-  int add(int a, int b);
-  
-  // Bad
-  /// @brief This function adds two numbers
-  int add(int a, int b);
+  class Foo {
+    Foo & get_instance() {
+      static Foo instance;
+      return instance;
+    }
+  };
   ```
-
-- 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:
+  </td><td>
 
   ```cpp
-  class Bad {
-      static Bad instance;
-      Bad & get_instance() { return instance; }
-  };
+  Foo Foo::instance {};
 
-  class Good {
-      Good & get_instance() {
-          static Good instance;
-          return instance;
-      }
+  class Foo {
+    static Foo instance;
+    Foo & get_instance() { return Foo::instance; }
   };
+
   ```
+  </td></tr></table>
 
-- Member variable default values should be directly defined in the class declaration instead of using the constructor.
+- Member variable default values should be directly defined in the class/struct
+  declaration instead of using the constructor.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  class Car {
-  private:
-      int speed = 0;
+  class Foo {
+    int speed = 0;
   };
   
-  // Bad
-  class Car {
-  private:
-      int speed;
-      Car() : speed(0) {}
-  };
   ```
-
-- Header files declare either a single class or symbols within a single namespace.
+  </td><td>
 
   ```cpp
-  // Good
-  // car.h
-  namespace crepe {
-      class Car {};
-  }
-  
-  // Bad
-  // car.h
-  namespace crepe {
-      class Car {};
-      class Engine {};
-  }
+  class Foo {
+    Foo() : speed(0) {}
+    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 calling template factory methods that explicitly name the return type in the function call signature
+  </td></tr></table>
+
+- Use of the `auto` type is *not* allowed, with the following exceptions:
+  - 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
+    in the function call signature
+    ```cpp
+    auto ptr = make_unique<Foo>();
+    ```
   - When fetching a singleton instance
-
-  ```cpp
-  // Good
-  for (auto item : items) {}
-  
-  auto instance = Singleton::get_instance();
-  
-  // Bad
-  auto speed = car.get_speed();
-  ```
+    ```cpp
+    auto & mgr = crepe::api::Config::get_instance();
+    ```
 
 - Only use member initializer lists for non-trivial types.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  class Car {
+  class Foo {
   public:
-      Car() : engine("V8") {}
+    Foo() : bar("baz") {}
   private:
-      std::string engine;
+    std::string bar;
   };
   
-  // Bad
-  class Car {
+  ```
+  </td><td>
+
+  ```cpp
+  class Foo {
   public:
-      Car() : speed(0) {}
+    Foo() : bar(0) {}
   private:
-      int speed;
+    int bar;
   };
   ```
+  </td></tr></table>
 
 - C++-style structs should define default values for all non-trivial fields.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  struct Car {
-      std::string model = "Unknown";
+  struct Foo {
+    int bar;
+    std::string baz;
   };
-  
-  // Bad
-  struct Car {
-      std::string model;
-      Car() : model("Unknown") {}
+  ```
+  </td><td>
+
+  ```cpp
+  struct Foo {
+    int bar = 0;
+    std::string baz;
   };
   ```
+  </td></tr></table>
 
-- Declare incomplete classes instead of including the relevant header where possible (i.e. if you only need a reference or pointer type).
+- Declare incomplete classes instead of including the relevant header where
+  possible (i.e. if you only need a reference or raw pointer).
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
-  class Engine;
-  class Car {
-      Engine* engine;
+  class Bar;
+  class Foo {
+    Bar & bar;
   };
   
-  // Bad
-  #include "engine.h"
-  class Car {
-      Engine* engine;
+  ```
+  </td><td>
+
+  ```cpp
+  #include "Bar.h"
+  class Foo {
+    Bar & bar;
   };
   ```
+  </td></tr></table>
 
-- Template functions are only declared in a `.h` header, and defined in a matching `.hpp` header.
+- Template functions are only *declared* in a `.h` header, and *defined* in a
+  matching `.hpp` header.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
+  add.h:
   ```cpp
-  // Good
-  // add.h
   template <typename T>
   T add(T a, T b);
+
+  #include "add.hpp"
+  ```
   
-  // add.hpp
+  add.hpp:
+  ```cpp
   #include "add.h"
+
   template <typename T>
   T add(T a, T b) {
-      return a + b;
+    return a + b;
   }
-  
-  // Bad
-  // add.h
+  ```
+  </td><td>
+
+  add.h:
+  ```cpp
   template <typename T>
   T add(T a, T b) {
-      return a + b;
+    return a + b;
   }
   ```
+  </td></tr></table>
 
-- Where possible, end (initializer) lists with a trailing comma (e.g. with structs, enums)
+- Where possible, end (initializer) lists with a trailing comma (e.g. with
+  structs, enums)
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
-  // Good
   enum Color {
-      Red,
-      Green,
-      Blue,
+    Red,
+    Green,
+    Blue,
   };
   
-  // Bad
+  ```
+  </td><td>
+
+  ```cpp
   enum Color {
-      Red,
-      Green,
-      Blue
+    Red,
+    Green,
+    Blue
   };
   ```
+  </td></tr></table>
+- `#pragma` should be used instead of include guards
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
-## CMakeLists specific
+  ```cpp
+  #pragma once
+
+  // ...
+  ```
+  </td><td>
+
+  ```cpp
+  #ifndef __INCLUDED_H
+  #define __INCLUDED_H
+
+  // ...
+
+  #endif
+  ```
+  </td></tr></table>
+
+## CMakeLists-specific
 
 - Make sure list arguments (e.g. sources, libraries) given to commands (e.g.
   `target_sources`, `target_link_libraries`) are on separate lines. This makes
   resolving merge conflicts when multiple sources were added by different
   people to the same CMakeLists.txt easier.
 
+# Structure
+
+- All engine-related code is implemented under the `crepe` namespace,
+  user-facing APIs under `crepe::api` (the folder structure should also reflect
+  this).
+- Do not (indirectly) include private *dependency* headers in API header files,
+  as these are no longer accessible when the engine is installed
+- 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.
+  <table><tr><th>Good</th><th>Bad</th></tr><tr><td>
+
+  ```cpp
+  /**
+   * \brief do something
+   *
+   * \param bar  Magic number
+   */
+  void foo(int bar);
+  ```
+  </td><td>
+
+  ```cpp
+  /**
+   * @brief do something
+   *
+   * @param bar  Magic number
+   */
+  void foo();
+  ```
+  </td></tr></table>
 
 # Libraries