1 GRPC C STYLE GUIDE 2 ===================== 3 4 Background 5 ---------- 6 7 Here we document style rules for C usage in the gRPC Core library. 8 9 General 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 16 Header 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 44 Variable Initialization 45 ----------------------- 46 47 When declaring a (non-static) pointer variable, always initialize it to `NULL`. 48 Even in the case of static pointer variables, it's recommended to explicitly 49 initialize them to `NULL`. 50 51 52 C99 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 60 Comments 61 -------- 62 63 Within public header files, only `/* */` comments are allowed. 64 65 Within implementation files and private headers, either single line `//` 66 or multi line `/* */` comments are allowed. Only one comment style per file is 67 allowed however (i.e. if single line comments are used anywhere within a file, 68 ALL comments within that file must be single line comments). 69 70 Symbol 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 88 Functions 89 ---------- 90 91 - The use of [`atexit()`](http://man7.org/linux/man-pages/man3/atexit.3.html) is 92 in forbidden in libgrpc. 93
