1 files changed, 83 insertions, 1 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc7e188..e946c8d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,5 +33,87 @@ Example:
 ```cpp
 // This file is part of the 64k demo project.
 // It implements the core audio synthesis engine.
-// Contact: demo-team@example.com
+// This is not a user-facing header, but an internal one.
 ```
+
+### Function and method comments
+
+Functions and methods, especially if they are internal non user-facing,
+should at least have a 1-line comment describing what they do or their
+how/when they should be called. Except if they are just 1-line function
+or very very short, obvious ones.
+
+### '#endif' directive
+
+The closing #endif directive must recall the corresponding opening #ifdef
+clause they are closing
+
+Example:
+```cpp
+#ifdef MY_TAG
+...some code
+#endif /* MY TAG */
+```
+
+We must also prefer '#if defined(MY_QUITE_LONG_TAG)' over '#ifdef MY_QUITE_LONG_TAG'
+especially if there's a risk of having later something like:
+```cpp
+#if defined(MY_TAG_1) && !defined(MY_TAG_2)
+```
+
+### use and abuse 'const' directives
+
+Especially for local variable, use 'const' qualification as much as
+possible.
+
+As an example, don't use:
+```cpp
+StructA variable_name = StructA(...);
+```
+
+but prefer instead:
+```cpp
+const StructA variable_name = StructA(...);
+```
+
+if variable_name is not mutated afterward.
+
+Also: pass parameter as "const ref" as much as possible
+(```const Struct& param``` instead of pointers or non-const refs)
+
+### put spaces around code and operators (cosmetics)
+
+Don't compact the code to much horizontally, and prefer adding extra
+spaces around code and operators.
+
+Example:
+```cpp
+const bool v = my_variable && (my_function() / 3. > (1. / x));
+const y = function_call(3, x, 2.);
+for (int x = 0; x < 24; ++x) { ... }
+```
+
+instead of
+```cpp
+const bool v=my_variable&&my_function()/3.>(1./x);
+const y = function_call(3,x,2);
+for(int x=0;x<24;++x){ ... }
+```
+
+### prefer prefixed incrementation over suffixed
+
+Use pre-incrementation:
+```cpp
+++x
+```
+
+instead of post-incrementation:
+
+```cpp
+x++
+```
+
+### use extra () for boolean operations
+
+Even if they are not strictly needed due to operator precedence rules,
+prefer adding extra ()'s around tests for clarity, with parcimony.