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.

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:

sudo apt-get install clang-format

Usage: (assuming you’ve configured your build into build directory)

ninja -C build clang-format

This make target reformats all source files in-place, so we recommend you first commit them (or add to git index with git add -A), reformat and then verify reformatting results using git diff (or git diff --cached if you used git add).

Warning

Because of bugs in clang-format and its questionable reformats in many places (seems it deals with C++ much better than with C) it’s intended only as a helper tool. Adding it to git pre-commit hooks is definitely a bad idea, at least currently.

C

We use a style derived (and slightly modified) from Google C++ Styleguide.

Code formatting

Note

See our .clang-format config for precise rules.

  1. Indentation: 4 spaces per level.

  2. Maximal line length: 100 characters.

  3. Brace placement:

    void f() {
        if (a && b) {
            something();
        }
    }
    
  4. if-else formatting:

    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:

    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:

    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.
  9. Assignments may be aligned when assigning some structurized data (e.g. struct members). Example:

    int some_int = 0;
    bool asdf = true;
    file->size      = 123;
    file->full_path = "/asdf/ghjkl";
    file->perms     = PERM_rw_r__r__;
    

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). The names i, j, k etc. should be limited to integers used as array indexes.

  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).
    4. “size” always means size in bytes, “length” (or “count”) means the number of elements (e.g. in an array, or characters in a C-string, excluding the terminating null byte).
  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).
  7. goto may be used only for error handling.

  8. Yoda conditions (e.g. if (42 == x)) or any other similar constructions are not allowed.

  9. Prefer sizeof(instance) to sizeof(type), it’s less error-prone.

Python

Todo

TBD

Meson

  1. 4-space indent, no tabs. Wrap lines at ~80-100 columns except for unbreakable things like URLs.

  2. First argument to target functions (shared_library, executable, custom_target, …) should be on the same line as opening paren. All other arguments should be on next lines, aligned to 4-space indent.

    Arguments to other functions should either be all on the same line, or there should be no argument on the same line as opening paren, and arguments should be in following lines, indented by 4 spaces.

  3. Otherwise, whitespace should generally follow PEP8 instead of meson suggested style (i.e., no space inside parens, no space before :).

  4. Variables named _prog refer to things obtained from find_program(). Auxiliary commands should reside in Scripts/, and the variable name is tied to the script name (see meson.build there). The scripts should be written in Python except for things that clearly benefit from being written in sh.