1GRPC C STYLE GUIDE
2=====================
3
4Background
5----------
6
7Here we document style rules for C usage in the gRPC Core library.
8
9General
10-------
11
12- Layout rules are defined by clang-format, and all code should be passed
13  through clang-format. A (docker-based) script to do so is included in
14  [tools/distrib/clang\_format\_code.sh](../tools/distrib/clang_format_code.sh).
15
16Header Files
17------------
18
19- Public header files (those in the include/grpc tree) should compile as
20  pedantic C89.
21- Public header files should be includable from C++ programs. That is, they
22  should include the following:
23  ```c
24  #ifdef __cplusplus
25  extern "C" {
26  # endif
27
28  /* ... body of file ... */
29
30  #ifdef __cplusplus
31  }
32  # endif
33  ```
34- Header files should be self-contained and end in .h.
35- All header files should have a `#define` guard to prevent multiple inclusion.
36  To guarantee uniqueness they should be based on the file's path.
37
38  For public headers: `include/grpc/grpc.h` → `GRPC_GRPC_H`
39
40  For private headers:
41  `src/core/lib/channel/channel_stack.h` →
42  `GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_H`
43
44Variable Initialization
45-----------------------
46
47When declaring a (non-static) pointer variable, always initialize it to `NULL`.
48Even in the case of static pointer variables, it's recommended to explicitly
49initialize them to `NULL`.
50
51
52C99 Features
53------------
54
55- Variable sized arrays are not allowed.
56- Do not use the 'inline' keyword.
57- Flexible array members are allowed
58  (https://en.wikipedia.org/wiki/Flexible_array_member).
59
60Comments
61--------
62
63Within public header files, only `/* */` comments are allowed.
64
65Within implementation files and private headers, either single line `//`
66or multi line `/* */` comments are allowed. Only one comment style per file is
67allowed however (i.e. if single line comments are used anywhere within a file,
68ALL comments within that file must be single line comments).
69
70Symbol Names
71------------
72
73- Non-static functions must be prefixed by `grpc_`
74- Static functions must *not* be prefixed by `grpc_`
75- Typenames of `struct`s , `union`s, and `enum`s must be prefixed by `grpc_` if
76  they are declared in a header file. They must not be prefixed by `grpc_` if
77  they are declared in a source file.
78- Enumeration values and `#define` names must be uppercase. All other values
79  must be lowercase.
80- Enumeration values or `#define` names defined in a header file must be
81  prefixed with `GRPC_` (except for `#define` macros that are being used to
82  substitute functions; those should follow the general rules for
83  functions). Enumeration values or `#define`s defined in source files must not
84  be prefixed with `GRPC_`.
85- Multiple word identifiers use underscore as a delimiter, *never* camel
86  case. E.g. `variable_name`.
87
88Functions
89----------
90
91- The use of [`atexit()`](http://man7.org/linux/man-pages/man3/atexit.3.html) is
92  in forbidden in libgrpc.
93