Add CODESTYLE.md

CODESTYLE.md

@@ -0,0 +1,116 @@
+# Coding Style Guidelines
+
+This document describes coding conventions and formatting styles we use in Graphene. All newly
+commited code must conform to them to pass a review.
+
+*Note: Old code is temporarily excluded from these rules until reformatted.*
+
+# Automatic Reformatting
+
+To make formatting easier we've added an integration with `clang-format` (currently only for C
+code). You must install appropriate package from your distribution to use it. For Ubuntu 18.04 you
+can setup it this way:
+
+```Bash
+sudo apt-get install clang-format
+```
+
+Usage: (assuming you're in the project's top directory)
+
+```Bash
+make format
+```
+
+This `make` target **reformats all source files in-place**, so we recommend you first commit them
+(or add to [git index](https://hackernoon.com/understanding-git-index-4821a0765cf) with `git add
+-A`), reformat and then verify reformatting results using `git diff` (or `git diff --cached` if you
+used `git add`).
+
+# C
+
+We use a style derived (and slightly modified) from [Google C++
+Styleguide](https://google.github.io/styleguide/cppguide.html).
+
+## Code formatting
+
+*See our [.clang-format](.clang-format) config for precise rules.*
+
+1. Indentation: 4 spaces per level.
+2. Maximal line length: 100 characters.
+3. Brace placement:
+```C
+void f() {
+    if (a && b) {
+       something();
+    }
+}
+```
+4. `if-else` formatting:
+```C
+if (x == y) {
+    ...
+} else if (x > y) {
+    ...
+} else {
+    ...
+}
+```
+5. Asterisks (`*`) should be placed on the left, with the type. Multiple pointer declarations in one
+line are disallowed. Example:
+```C
+int* pointer;
+int* another_pointer;
+int non_pointer_a, non_pointer_b, non_pointer_c;
+```
+6. Function call/declaration folding: aligned to a matching parenthesis.
+Required only if the one-line version would exceed the line length limit.
+Examples:
+```C
+int many_args(int something_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+              int also_looooooong,
+              int c);
+...
+many_args(some_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong_calculations,
+          many_args(123,
+                    also_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+                    789),
+          many_args(1, 2, 3));
+```
+7. `if`, `else`, `do`, `for`, `while`, `switch` and `union` should be followed by a space.
+8. Includes should be grouped and then sorted lexicographically. Groups should be separated using a
+single empty line.
+Groups:
+    1. Matching `.h` header for `.c` files.
+    2. Standard library headers.
+    3. Non-standard headers not included in Graphene's repository (e.g. from external dependencies,
+    like `curl.h`).
+    4. Graphene's headers.
+
+## Conventions and High-level Style
+
+1. Variable and function names should be sane and easy to understand (example: `nofpts` is bad,
+`points_cnt` is ok).
+2. All non-static function interfaces should be documented in comments (especially pointer
+ownerships). Same for public macros.
+3. Prefer readable code and meaningful variable/function names to explaining implementation details
+in comments within a function. Only tricky or unintuitive code should be commented.
+4. Magic numbers (e.g. buffer sizes) shouldn’t be hardcoded in the implementation. Use `#define`.
+5. Naming:
+    1. Macros and global constants should be `NAMED_THIS_WAY`.
+    2. Functions, structures and variables should be `named_this_way`.
+    3. Global variables should be prefixed with `g_` (e.g. `g_thread_list`).
+
+6. Types:
+    1. All in-memory sizes and array indexes should be stored using `size_t`.
+    2. All file offsets and sizes should be stored using `uint64_t`.
+    3. In general, C99 types should be used where possible (although some code is "grandfathered"
+    in, it should also be changed as time allows).
+
+8. `goto` may be used only for error handling.
+10. [Yoda conditions](https://en.wikipedia.org/wiki/Yoda_conditions) (e.g. `if (42 == x)`) or any
+other similar constructions are not allowed.
+11. Prefer `sizeof(instance)` to `sizeof(type)`, it’s less error-prone.
+
+# Python
+
+TODO

CONTRIBUTING.md

@@ -42,7 +42,7 @@ In general, a PR should:
 1. Address a single problem; i.e., it should add one feature or fix one issue.  Fixes for distinct issues should be separated into multiple PRs.
 2. Clearly explain the problem and solution in the PR and commit messages, using grammatically correct English.
 3. Include unit tests for the new behavior or bugfix, except in special circumstances, namely: when designing a unit test is difficult (e.g., the code is deep enough in Graphene that it would require extra hooks for testing) or cannot be easily tested (e.g., a performance fix).
-4. Follow project style guidelines.
+4. Follow [project style guidelines](CODESTYLE.md).
 
 ### PR Life Cycle
 
@@ -59,7 +59,7 @@ In general, a PR should:
 Before a pull request is merged, it must:
 
   1. Pass all CI tests
-  2. Follow project style guidelines (see below)
+  2. Follow [project style guidelines](CODESTYLE.md).
   3. Introduce no new compilation errors or warnings
   4. Have all discussions from reviewers resolved
   5. Have a clear, concise and grammatically correct comments and commit messages.
@@ -87,7 +87,7 @@ Additional reviews from anyone are welcome.
 
 ### Style Guidelines
 
-TODO
+See [style guidelines](CODESTYLE.md).
 
 ## Running Regression Tests by Hand