included in the source as straight UTF-8.


Braced Initializer Lists ~

Format a braced list exactly like you would format a function call in its
place but with one space after the `{` and one space before the `}`

If the braced list follows a name (e.g. a type or variable name), format as if
the `{}` were the parentheses of a function call with that name. If there is
no name, assume a zero-length name. >c

    struct my_struct m = {  // Here, you could also break before {.
        superlongvariablename1,
        superlongvariablename2,
        { short, interior, list },
        { interiorwrappinglist,
          interiorwrappinglist2 } };


Loops and Switch Statements ~

Annotate non-trivial fall-through between cases.

If not conditional on an enumerated value, switch statements should always
have a `default` case (in the case of an enumerated value, the compiler will
warn you if any values are not handled). If the default case should never
execute, simply use `abort()`: >c

    switch (var) {
      case 0:
        ...
        break;
      case 1:
        ...
        break;
      default:
        abort();
    }

Switch statements that are conditional on an enumerated value should not have
a `default` case if it is exhaustive. Explicit case labels are preferred over
`default`, even if it leads to multiple case labels for the same code. For
example, instead of: >c

    case A:
      ...
    case B:
      ...
    case C:
      ...
    default:
      ...

You should use: >c

    case A:
      ...
    case B:
      ...
    case C:
      ...
    case D:
    case E:
    case F:
      ...

Certain compilers do not recognize an exhaustive enum switch statement as
exhaustive, which causes compiler warnings when there is a return statement in
every case of a switch statement, but no catch-all return statement. To fix
these spurious errors, you are advised to use `UNREACHABLE` after the switch
statement to explicitly tell the compiler that the switch statement always
returns and any code after it is unreachable. For example: >c

    enum { A, B, C } var;
    ...
    switch (var) {
      case A:
        return 1;
      case B:
        return 2;
      case C:
        return 3;
    }
    UNREACHABLE;

Return Values ~

Do not needlessly surround the `return` expression with parentheses.

Use parentheses in `return expr;` only where you would also use them in
`x = expr;`. >c

    return result;
    return (some_long_condition && another_condition);

    return (value);  // You wouldn't write var = (value);
    return(result);  // return is not a function!


Horizontal Whitespace ~

Use of horizontal whitespace depends on location.

    Variables ~
>c
        int long_variable = 0;  // Don't align assignments.
        int i             = 1;

        struct my_struct {  // Exception: struct arrays.
          const char *boy;
          const char *girl;
          int pos;
        } my_variable[] = {
          { "Mia",       "Michael", 8  },
          { "Elizabeth", "Aiden",   10 },
          { "Emma",      "Mason",   2  },
        };
<

==============================================================================
Parting Words

The style guide is intended to make the code more readable. If you think you
must violate its rules for the sake of clarity, do it! But please add a note
to your pull request explaining your reasoning.


 vim:tw=78:ts=8:et:ft=help:norl: