C Coding Style Guide.rst

int GetCount(void);                 // Bad: inaccurate description.
int GetActiveConnectCount(void);    // Good
int PrefixFuncName(void);   // OK: CamelCase, with no prefix in the format, but prefix in the content.

enum XxxMyEnum {            // OK.
    ...
};
AddTableEntry() // OK
DeleteUser()    // OK
GetUserInfo()   // OK
DataReady()     // OK
IsRunning()     // OK
JobDone()       // OK
TotalCount()    // OK
GetTotalCount() // OK
int g_activeConnectCount;

void Func(void)
{
    static int pktCount = 0;
    ...
}
int Func(...)
{
    enum PowerBoardStatus powerBoardStatusOfSlot; // Not good: Long redundant local variable.
    powerBoardStatusOfSlot = GetPowerBoardStatus(slot);
    if (powerBoardStatusOfSlot == POWER_OFF) {
        ...
    }
    ...
}
int Func(...)
{
    enum PowerBoardStatus status;   // Good: The status can be clearly expressed in context.
    status = GetPowerBoardStatus(slot);
    if (status == POWER_OFF) {
        ...
    }
    ...
}
int i;
...
for (i = 0; i < COUNTER_RANGE; i++) {
    ...
}
int Mul(int a, int b)
{
    return a * b;
}
struct MsgHead {
    enum MsgType type;
    int msgLen;
    char *msgBuf;
};

union Packet {
    struct SendPacket send;
    struct RecvPacket recv;
};

enum BaseColor {
    RED,    // Note: The enumeration is in UpperCamelCase style while the enumerated values adopt the macro naming style.
    GREEN,
    BLUE
};

typedef int (*NodeCmpFunc)(struct Node *a, struct Node *b);
typedef struct {    // Good: The anonymous struct is used because self-nesting is not required.
    int a;
    int b;
} MyType;           // Struct alias with UpperCamelCase.

```c
typedef struct tagNode {    // Good: Add the 'tag' prefix or use 'Node_'.
    struct tagNode *prev;
    struct tagNode *next;
} Node;             // UpperCamelCase.
#define PI 3.14
#define MAX(a, b)   (((a) < (b)) ? (b) : (a))
#ifdef SOME_DEFINE
void Bar(int);
#define Foo(a) Bar(a)   // The function-like macro is named as a function style.
#else
void Foo(int);
#endif
const int VERSION = 200;    // OK.

const enum Color DEFAULT_COLOR = BLUE; // OK.

const char PATH_SEP = '/';  // OK.

const char * const GREETINGS = "Hello, World!"; // OK.
// Structure type does not meet the definition of constant.
const struct MyType g_myData = { ... };     // OK: Name it in lowerCamelCase style.

// Array type does not meet the definition of constant.
const int g_xxxBaseValue[4] = { 1, 2, 4, 8 };   // OK: Name it in lowerCamelCase style.

int Foo(...)
{
    // The scope does not meet the definition of constant.
    const int bufSize = 100;    // OK: Name it in lowerCamelCase style.
    ...
}
// Note: The enumeration type name is in the UpperCamelCase style, while enumerated values are all capitalized and separated with underscores (_).
enum BaseColor {
    RED,
    GREEN,
    BLUE
};
#define SWAP_INT(a, b) do { \
    int tmp_ = a; \
    a = b; \
    b = tmp_; \
} while (0)
#ifndef XXX_YYY_ZZZ
#error Header aaaa/bbbb/cccc/abc.h must only be included after xxxx/yyyy/zzzz/xyz.h
#endif
struct MyType {     // Good: Follow the statement to the end, and indent one space.
    ...
};                  // Good: The right brace is followed by the semicolon.

int Foo(int a)
{                   // Good: The left brace of the function starts a new line, and nothing else is placed on the line.
    if (...) {
        ...
    } else {        // Good: The 'else' statement follows the right brace.
        ...
    }               // Good: The right brace takes a single line.
}
ReturnType FunctionName(ArgType paramName1, ArgType paramName2)   // Good：All in one line
{
    ...
}

ReturnType VeryVeryVeryLongFunctionName(ArgType paramName1,     // The line length cannot accommodate all parameters and thus a line break is required.
                                        ArgType paramName2,     // Good：Aligned with the previous line.
                                        ArgType paramName3)
{
    ...
}

ReturnType LongFunctionName(ArgType paramName1, ArgType paramName2, // Subject to line length, a line break is required.
    ArgType paramName3, ArgType paramName4, ArgType paramName5)     // Good: After the line break, 4 spaces are used for indentation.
{
    ...
}

ReturnType ReallyReallyReallyReallyLongFunctionName(            // The line length cannot accommodate the first parameter, and thus a line break is required.
    ArgType paramName1, ArgType paramName2, ArgType paramName3) // Good: After the line break, 4 spaces are used for indentation.
{
    ...
}
ReturnType result = FunctionName(paramName1, paramName2);   // Good：Function parameters are placed in one line.

ReturnType result = FunctionName(paramName1,
                                 paramName2,                // Good：Aligned with the above parameters.
                                 paramName3);

ReturnType result = FunctionName(paramName1, paramName2,
    paramName3, paramName4, paramName5);                    // Good：After the line break, 4 spaces are used for indentation.

ReturnType result = VeryVeryVeryLongFunctionName(           // The line length cannot accommodate the first parameter, and thus a line break is required.
    paramName1, paramName2, paramName3);                    // After the line break, 4 spaces are used for indentation.
// Good：The parameters in each line represent a group of data structures with a strong correlation. They are placed on one line for ease of understanding.
int result = DealWithStructureLikeParams(left.x, left.y,     // Indicates a group of parameters.
                                         right.x, right.y);  // Indicates another group of related parameters.
if (objectIsNotExist) {         // Good: Braces are added to a single-line conditional statement.
    return CreateNewObject();
}
if (someConditions) {
    ...
} else {    // Good: The 'else' is in a different line of 'if'.
    ...
}
if (someConditions) { ... } else { ... } // Bad: They are in the same line.
for (int i = 0; i < someRange; i++) {   // Good: Braces are used.
    DoSomething();
}
while (condition) { }   // Good: The while loop body is empty. And braces are used.
while (condition) {
    continue;           // Good: The continue keyword highlights the end of the empty loop. And braces are used.
}
for (int i = 0; i < someRange; i++)
    DoSomething();      // Bad: Braces should be added.
while (condition);      // Bad: Using semicolons will make people misunderstand which code is a part of the while statement.
switch (var) {
    case 0:             // Good: Indented
        DoSomething1(); // Good: Indented
        break;
    case 1: {           // Good: Braces are added.
        DoSomething2();
        break;
    }
    default:
        break;
}
switch (var) {
case 0:                 // Bad: 'case' not indented
    DoSomething();
    break;
default:                // Bad: 'default' not indented
    break;
}
// Pretend that the following first line does not meet the line length requirement.
if ((currentValue > MIN) &&  // Good: After the line break, the Boolean operator is placed at the end of the line.
    (currentValue < MAX)) {
    DoSomething();
    ...
}

int result = reallyReallyLongVariableName1 +    // Good: The plus sign is placed at the end of the line.
             reallyReallyLongVariableName2;
int sum = longVaribleName1 + longVaribleName2 + longVaribleName3 +
    longVaribleName4 + longVaribleName5 + longVaribleName6;         // OK: indented with 4 spaces

int sum = longVaribleName1 + longVaribleName2 + longVaribleName3 +
          longVaribleName4 + longVaribleName5 + longVaribleName6;   // OK: aligned
int maxCount = 10;
bool isCompleted = false;
int maxCount = 10; bool isCompleted = false; // Bad: Multiple initialization statements are placed on the same line.
int x, y = 0;  // Bad: Variable definitions need to be placed on different lines. Each definition occupies one line.

int pointX;
int pointY;
...
pointX = 1; pointY = 2;  // Bad: Multiple variable assignment statements are placed on the same line.
int i, j;  // Good: Multiple variables that are defined and do not need to be initialized immediately can be written in one line.
for (i = 0; i < row; i++) {
    for (j = 0; j < col; j++) {
        ...
    }
}
// Good: No line break for a short line.
int arr[4] = { 1, 2, 3, 4 };

// Good: A line break here makes the readability better.
const int rank[] = {
    16, 16, 16, 16, 32, 32, 32, 32,
    64, 64, 64, 64, 32, 32, 32, 32
};
int a[][4] = {
    { 1, 2, 3, 4 }, { 2, 2, 3, 4 }, // OK.
    { 3, 2, 3, 4 }, { 4, 2, 3, 4 }
};

int b[][8] = {
    { 1, 2, 3, 4, 5, 6, 7, 8 },     // OK.
    { 2, 2, 3, 4, 5, 6, 7, 8 }
};
int c[][8] = {
    {
        1, 2, 3, 4, 5, 6, 7, 8      // OK.
    }, {
        2, 2, 3, 4, 5, 6, 7, 8
    }
};
struct Date {
    int year;
    int month;
    int day;
};

struct Date date = {    // Good: When the designated initializer is used, each member is initialized on a separate line.
    .year   = 2000,
    .month  = 1,
    .day    = 1
};
int *p1;    // OK.
int* p2;    // OK.

int*p3;     // Bad: No spaces.
int * p4;   // Bad: Spaces on both sides.
int* a, b;  // Bad: It is easy to misinterpret b as a pointer.
char * const VERSION = "V100";      // OK.
int Foo(const char * restrict p);   // OK.
#if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16) // Good: "#" is at the beginning of the line.
#define ATOMIC_X86_HAS_CMPXCHG16B 1  // Good: "#" is at the beginning of the line.
#else
#define ATOMIC_X86_HAS_CMPXCHG16B 0
#endif

int FunctionName(void)
{
    if (someThingError) {
        ...
#ifdef HAS_SYSLOG        // Good: "#" is at the beginning of the line even though it's in a function body.
        WriteToSysLog();
#else
        WriteToFileLog();
#endif
    }
}
#if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16)
    #define ATOMIC_X86_HAS_CMPXCHG16B 1  // Good: Statements are layered, facilitating reading.
#else
    #define ATOMIC_X86_HAS_CMPXCHG16B 0
#endif
int i = 0;                  // Good: When the variable is initialized, there should be spaces before and after the =. Do not leave a space before the semicolon.
int buf[BUF_SIZE] = {0};    // Good: During array initialization, spaces in curly braces are optional.
int arr[] = { 10, 20 };     // Good: A space is added before and after the brace.
int result = Foo(arg1,arg2);
                      ^         // Bad: There should be a space after the comma.

int result = Foo( arg1, arg2 );
                 ^          ^   // Bad: No space should be added to either side in the parentheses.
x = *p;     // Good: There is no space between the operator * and the pointer p.
p = &x;     // Good: There is no space between the operator & and the variable x.
x = r.y;    // Good: When a member variable is accessed through the operator (.), no space is added.
x = r->y;   // Good: When a member variable is accessed through the operator (.), no space is added.
x = 0;    // Good: A space must be added before and after the assignment operator (=).
x = -5;   // Good: Do not add spaces before the minus sign (-) and the number.
++x;      // Good: Do not add spaces before the minus sign (-) and the number.
x--;

if (x && !y)        // Good: A space must be added before and after the Boolean operator. Do not leave spaces between the ! operator and variables.
v = w * x + y / z;  // Good: A space must be added before and after binary operators.
v = w * (x + z);    // Good: No space is required before and after the expression in the parentheses.
if (condition) {    // Good: A space is added between the if keyword and the parenthesis and no space is added before or after the conditional statement inside the parentheses.
    ...
} else {            // Good: A space is added between the else keyword and the curly brace.
    ...
}

while (condition) {}    // Good: A space is added between the while keyword and the parenthesis. No space is added before or after the conditional statement inside the parentheses.

for (int i = 0; i < someRange; ++i) {  // Good: A space is added between the for keyword and the parenthesis, and after the semicolons (;).
    ...
}

switch (var) {  // Good: A space is added after the switch keyword.
    case 0:     // Good: No space is added between the case conditional statement and the colon.
        ...
        break;
    ...
    default:
        ...
        break;
}
ret = DoSomething();

if (ret != OK) {    // Bad: Return value judgment should follow the function call.
    return -1;
}
int Foo(void)
{
    ...
}


int Bar(void)       // Bad: Use no more than two continuous blank lines.
{
    ...
}
int Foo(void)
{

    DoSomething();  // Bad: The blank lines above and below are unnecessary.
    ...

}
// Single-line function header
int Func1(void);

// Multi-line function header
// Second line
int Func2(void);
/* Single-line function header */
int Func1(void);

/*
 * Single-line or multi-line function header
 * Second line
 */
int Func2(void);
/*
 * The number of written bytes is returned. If -1 is returned, the write operation fails.
 * Note that, the memory buffer is released by the caller.
 */
int WriteString(char *buf, int len);
/*
 * Function name: WriteString
 * Function: Write a character string.
 * Parameter:
 * Return value:
 */
int WriteString(char *buf, int len);
// Single-line comment
DoSomething();

// Multi-line comment
// Second line
DoSomething();
/*Single-line comment */
DoSomething();

/*
 * Single-/Multi-line comment
 * Second line
 */
DoSomething();
int foo = 100;  // Comment on the right
int bar = 200;  /* Comment on the right */
#define A_CONST 100         /* Related comments of the same type can be aligned vertically. */
#define ANOTHER_CONST 200   /* Leave spaces after code to align comments vertically. */
// TODO(<author-name>): Supplement to XX
// FIXME: XX defect
switch (var) {
    case 0:
        DoSomething();
        /* fall-through */
    case 1:
        DoSomeOtherThing();
        ...
        break;
    default:
        DoNothing();
        break;
}
switch (var) {
    case 0:
    case 1:
        DoSomething();
        break;
    default:
        DoNothing();
        break;
}
#ifndef FOO_H
#define FOO_H

int Foo(void);  // Good: Declare an external interface in the header file.

#endif
static void Bar(void);  // Good: The declaration of the internal function is placed in the header of the .c file, declaring its static scope.

void Foo(void)
{
    Bar();
}

static void Bar(void)
{
    // Do something;
}
#ifndef TIMER_INCLUDE_TIMER_H
#define TIMER_INCLUDE_TIMER_H

...

#endif
extern int Foo(void);   // Bad: Reference external functions by using the extern declaration.
void Bar(void)
{
    int i = Foo();  // Here, the external interface Foo is used.
    ...
}
#include "b.h"      // Good: Use the interface providing the interface.
void Bar(void)
{
    int i = Foo();
    ...
}
int Foo(void);
int Foo(void)
{
    // Do something
}
...
#ifdef __cplusplus
void Foo(int);
#define A(value) Foo(value)
#else
void A(int)
#endif
...
#ifdef __cplusplus
extern "C" {
#endif

#include "a.h"
void B(void);

#ifdef __cplusplus
}
#endif
extern "C" {
    void Foo(int);
    void B(void);
}
int Foo(...)
{
    if (received) {
        type = GetMsgType(msg);
        if (type != UNKNOWN) {
            return DealMsg(...);
        }
    }
    return -1;
}
int Foo(...)
{
    if (!received) {    // Good: Use the 'guardian statement'.
        return -1;
    }

    type = GetMsgType(msg);
    if (type == UNKNOWN) {
        return -1;
    }

    return DealMsg(..);
}
char fileHead[128];
ReadFileHead(fileName, fileHead, sizeof(fileHead)); // Bad: The returned value is not checked.

DealWithFileHead(fileHead, sizeof(fileHead));       // The 'fileHead' is possibly invalid.
char fileHead[128];
ret = ReadFileHead(fileName, fileHead, sizeof(fileHead));
if (ret != OK) {                // Good: Ensure that the 'fileHead' is written.
    return ERROR;
}

DealWithFileHead(fileHead, sizeof(fileHead));       // Process the file header.
struct FooNode {
    struct List link;
    int foo;
};

struct BarNode {
    struct List link;
    int bar;
}

void FooListAddNode(void *node) // Bad: Here, the void * type is used to pass parameters.
{
    FooNode *foo = (FooNode *)node;
    ListAppend(&g_fooList, &foo->link);
}

void MakeTheList(...)
{
    FooNode *foo;
    BarNode *bar;
    ...

    FooListAddNode(bar);        // Wrong: In this example, the foo parameter was supposed to be passed, but the bar parameter is incorrectly passed instead. No error is reported immediately and issues may occur as a result.
}
void FooListAddNode(FooNode *foo)
{
    ListAppend(&g_fooList, &foo->link);
}
int SomeProc(...)
{
    int data;

    bool dataOK = GetData(&data);       // Get data.
    if (!dataOK) {                      // Check the result of the previous step ensuring data validity.
        return -1;
    }

    DealWithData(data);                 // Call the data processing function.
    ...
}

void DealWithData(int data)
{
    if (data < MIN || data > MAX) {     // Bad: The caller has already ensured the validity of the data.
        return;
    }

    ...
}
int strncmp(const char *s1, const char *s2, size_t n); // Good: The invariant parameter is declared as const.