Add STYLE.md

[cole-miller]

Let's use this PR to arrive at a consensus about what style new dqlite code should follow. Once that consensus is reached, I'll add more commits updating .clang-format and .clang-tidy and reformatting existing code as needed.

Signed-off-by: Cole Miller cole.miller@canonical.com

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.21%. Comparing base (e814a1c) to head (e60adcd).
Report is 19 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #573      +/-   ##
==========================================
- Coverage   81.23%   81.21%   -0.02%     
==========================================
  Files         192      192              
  Lines       27061    27061              
  Branches     4980     4984       +4     
==========================================
- Hits        21982    21978       -4     
- Misses       3436     3490      +54     
+ Partials     1643     1593      -50     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[just-now]

What's your opinion regarding adding the following statements to the coding style:

1. if-s and while-s must have no side effects:
   example:

if (q_empty(q)) ... // OK

while(pop(q)) ... // not OK

2. Introduce more verbose differences between NULL, 0, false in the code adding explicit conditions:

if (p == NULL) /* for pointers */
if (!b) /* for booleans */
while (in_flight == 0) /* for integers*/

3. Use inline functions instead of macros whenever it's possible.

4. Also, can we eventually move to return code conventions from kernel, where 0 is success, negative error code for a failure, positive values for non failures (ex: bytes read)

5. All macros are written such a way it's possible to use without putting additional parentheses over their parameters.

6. Use PRE()/POST()/assert() to document assumptions in the code.

[cole-miller]

1. Agreed.
2. We use explicit comparisons to NULL and 0 in the current code, so let's stick with that.
3. Agreed, obviously there's a lot of macro stuff in the current codebase but let's try to limit that going forward.
4. This is tough because basically all our functions use positive return codes to signal errors right now. We definitely need some kind of reform here because (similar to the allocator situation) our functions are split between using raft return codes, SQLite codes, dqlite codes, and I think libuv codes in a few cases. But I'm not sure what our stated policy should be in this document.
5. Agreed.
6. Sure!

[cole-miller]

Okay, going to experiment with automated reformatting/rewriting now...