add a contributor guide

1 files changed, 116 insertions, 0 deletions

diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..4a829b3
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,116 @@
+# Contributor guide for melonDS
+
+Please follow a style as documented here. Note that this guide was not always enforced, so some parts of the code violate it.
+
+```c++
+
+// for single line comments prefer C++ style
+
+/*
+    for multiline comments
+    both C style comments
+*/
+// as well as
+// C++ style comments are possible
+
+// namespaces in PascalCase
+namespace Component
+{ // for all constructs curly braces go onto the following line
+
+// the content of namespaces should not be indented
+
+int GlobalVariable; // in PascalCase
+
+// function names should use PascalCase, parameters camelCase:
+void Test(int someParam)
+{
+    int variable = someParam * 2; // local variables in camelCase
+    
+    // you can slightly vary the spacing around operators:
+    int variable2 = someParam*2 + 1;
+    // but avoid something like this: someParam* 2+ 3
+
+    for (int i = 0; i < variable; i++) // always a space between if/for/while and the braces
+    {
+        // not using curly braces is allowed
+        // if the body of the if/for/while is simple:
+        if ((i % 2) == 0)
+            printf("%d\n", i); // no space between the function name and the braces
+    }
+}
+
+class MyClass // PascalCase
+{
+public: // access specfications are not indented
+    void Test(int param) // for methods the same rules apply as for functions
+    {
+    }
+
+private:
+    int MemberVariable; // PascalCase, no prefix
+};
+
+enum
+{
+    // enums should always have a common prefix in camelCase
+    // separated by an underscore with the item name
+    // which has to be in PascalCase
+    enumPrefix_FirstElement,
+    enumPrefix_SecondElement,
+    enumPrefix_ThirdElement,
+    enumPrefix_FourthElement,
+};
+
+}
+
+```
+
+Some additional notes:
+
+* Keep the definition and initialisation of local variables in one place and keep the scope of local variables as small as possible.
+
+**That means avoid code like this**:
+```cpp
+void ColorConvert(u32* dst, u16* vram)
+{
+    u16 color;
+    u8 r, g, b;
+    int i;
+
+    for (i = 0; i < 256; i++)
+    {
+        color = vram[i];
+        r = (color & 0x001F) << 1;
+        g = (color & 0x03E0) >> 4;
+        b = (color & 0x7C00) >> 9;
+
+        dst[i] = r | (g << 8) | (b << 16);
+    }
+}
+```
+
+**Do this instead:**
+```cpp
+void ColorConvert(u32* dst, u16* vram)
+{
+    for (int i = 0; i < 256; i++)
+    {
+        u16 color = vram[i];
+        u8 r = (color & 0x001F) << 1;
+        u8 g = (color & 0x03E0) >> 4;
+        u8 b = (color & 0x7C00) >> 9;
+
+        dst[i] = r | (g << 8) | (b << 16);
+    }
+}
+```
+
+* For integer types preferably use the explictly typed ones. We have short aliases for them defined in types.h (for unsigned types: `u8`, `u16`, `u32`, `u16`. For signed `s8`, `s16`, `s32`, `s64`). In some situations like loop variables, using `int` is possible as well.
+* Don't overdo object oriented programming. Always try to use a simpler construct first, only use a polymorphic class if a namespace with functions in it doesn't cut it.
+
+* In doubt put a namespace around your part of the code.
+
+* C style strings (and the associated functions from the C standard library) are used in most places. We are thinking about changing this, as C strings are a bit of a hassle to deal with, but for the time being this is what we use.
+* Only the C standard IO is used (so use `printf`, `fopen`, … Do not use `std::cout`/`std::ostream`, …).
+* Complex C++ containers can be used (`std::vector`, `std::list`, `std::map`, …). `std::array` is usually not used, unless necessary so that the container can be used with other C++ constructs (e.g. `<algorithm>`). Only use them if a C array doesn't cut it.
+* And at last, if you have any questions, visit us on IRC (see the readme)!