C编码风格与规范

add/remove      begin/end           create/destroy      insert/delete 
first/last      get/release         increment/decrement put/get/add/delete
lock/unlock     open/close          min/max             old/new 
start/stop      next/previous       source/target       show/hide 
send/receive    source/destination  copy/paste          up/down

/* 不允许, 正点原子采用这种方式是为了兼容C89 */
int i;
for (i = 0; i < count; i++) {
    list[i] = ...
}
/* 使用下面的方式让循环变量的作用域只在for循环里 */
/* PS: C标准至少在C99以上, C89这样写会报错 */
for (int i = 0; i < count; i++) {
    list[i] = ...
}

/*
某个模块的文件结构：
model_root
├─foldA
│  └─functionA.h
├─foldB
│  └─functionB.h
├─foldC
│  └─functionC.h
├─foldnD
│  └─functionD.h
├─foldE
│  └─functionE.h
└─foldF
   └─functionF.h
假如都需要这6个模块的头文件, IncludePath中只添加了model_root. 
*/

/* 你当然可以大力出奇迹, 将这6个文件夹全部添加到IncludePath中, 然后 */
#include "functionA.h"
#include "functionB.h"
...
#include "functionF.h"

/* 但更好的做法是, 不添加IncludePath, 使用相对路径包含, 保证根目录在IncludePath就可以 */
#include "./flodA/functionA.h"
#include "./foldB/functionB.h"
...
#include "./foldF/functionf.h"

/**
 * @file    xxx.h
 * @brief   balabala
 * @auhor   yourname
 * @date    2024-02-20
 * @version 0.1
 */

#ifndef __XXX_H
#define __XXX_H

...

#endif  /* __XXX_H */

/* 运算符与数组下标 */
data[3] = (uint8_t)(verify_key >> 8);
for (int i = 0; i <= num; i++) {
    datax->buf[i] = x1 * (x2 + i) + baseval;
}

/* 声明指针变量 */
char *str = NULL;

/* 花括号使用案例 */
/**
 * @brief 按键扫描
 *
 * @param mode 是否支持连按
 *  0-不支持连按, 1-支持连按
 * @return 按下的按键
 *  @retval 按下:`KEY0_PRES ~ WKUP_PRES`
 *  @retval 未按下:`0`
 * @note 注意此函数有响应优先级,`KEY0 > KEY1 > WK_UP`
 */
uint8_t key_scan(uint8_t mode) {
    static uint8_t key_up = 1; /* 按键松开标志 */
    if (mode == 1) {
        key_up = 1; /* 支持连按 */
    }
    if (key_up && (KEY0 == 0 || KEY1 == 0 || WK_UP == 1)) {
        delay_ms(10);
        key_up = 0;
        if (KEY0 == 0) {
            return KEY0_PRES;
        } else if (KEY1 == 0) {
            return KEY1_PRES;
        } else if (WK_UP == 1) {
            return WKUP_PRES;
        }
    } else if (KEY0 == 1 && KEY1 == 1 && WK_UP == 0) {
        key_up = 1;
    }
    return 0; /* 无按键按下 */
}

/* 括号内换行 */
xTaskCreate((TaskFunction_t)start_task, /* 任务函数 */
            (const char *)"start_task", /* 任务名称 */
            (uint16_t)START_STK_SIZE,   /* 任务堆栈大小 */
            (void *)NULL,               /* 传入给任务函数的参数 */
            (UBaseType_t)START_TASK_PRIO,           /* 任务优先级 */
            (TaskHandle_t *)&g_start_task_handler); /* 任务句柄 */

/* 下一行的位置与第一行括号后的第一个字符对齐, 最后的右括号不换行 */
ring_fifo_t *ring_fifo_init(void *buf, uint32_t size,
                            enum ring_fifo_type type);

/**
 * @brief 用户从快递柜取包裹
 * 
 * @param pick_up_code 取件码
 * @return status_t 操作状态
 */
status_t user_pick_up_express(uint32_t pick_up_code) {
    if (pick_up_code == 0) {
        return ERR_INPUT_NULL;
    }
// 11行，这里空一行
    uint32_t cabinet_number = seek_express_by_code(pick_up_code);
    if (cabinet_number == 0) {
        /* 柜子编号不存在 */
        return ERR_NO_FOUND;
    }
// 17行，这里空一行
    status_t cabient_status = cabient_open_the_door(cabient_number);
    if (cabient_status == ERROR) {
        /* 开门出错, 可能是柜子继电器出问题了, 提示联系管理员 */
        return ERR_OPEN_DOOR;
    }
// 23行，这里空一行
    return OK;
}

/* 不规范写法 */
a = x + y; b = x - y;
a = b = 0;

/* 规范写法 */
a = x + y;
b = x - y;
a = 0;
b = 0;

/* 不规范写法 */
if (condition)
    return true;

if (condition) return true;

if (condition) { return true; }

if (condition) {} else {
    ...
}
while (condition) {
}

/* 规范写法 */
if (condition) {
    return true;
}
/* 空语句规范写法 */
while (condition) {}
/* 如果不用上面的方式, 可以采用下面的方式. 如果分号不换行易被误认成函数调用 */
while (condition)
    ;
/* if else中的空语句括号需换行. 如果大括号中间不换行易被误认成if条件成立后执行 */
if (condition) {
} else {
    ...
}

uint32_t arr[4];
int16_t foo;
/* 不允许未定义就使用arr数组 */
printf("%d", a[1]);
/* 不允许使用未定义的变量 */
int16_t bar = foo + 1;

/* 对于不确定内容的数组, 使用memset初始化 */
memset(arr, 0, sizeof(arr));
/* 申请堆内存时, 使用calloc可以将申请的内存设置为零 */
uint16_t *new_data = (uint16_t *)calloc(sizeof(uint16_t) * MAX_LEN);

/* 正确写法 */
typedef struct foo {   /* 此处foo可写可不写, 不写就是匿名结构体. 如果有像下面这样需要引用该结构体指针的那必须写 */
    struct foo *next;  /*!< next item */
    int index;         /*!< index of item */
    uint8_t flag;      /*!< flag of item */
    ...
} foo_t;               /* 使用_t后缀 */
foo_t foo_obj;         /* 定义结构体变量 */

/* 错误写法 */
struct foo {
    struct foo *next;  /*!< next item */
    int index;         /*!< index of item */
    uint8_t flag;      /*!< flag of item */
    ...
};
sturct foo foo_obj;         /* 定义结构体变量 */

/* 特殊情况, 只声明一个或几个结构体变量, 这种不用typedef名词 */
/* 如果内部使用考虑是否需要static修饰符, 加在struct前面 */
struct foo {
    int index_of_foo;      /*!< 索引 */
    data_t data_of_foo;    /*!< 数据 */
    ...
} foo_variable_1, foo_variable_2 ... ;

/**
 * @brief GPIO电平定义
 */
typedef enum {
    GPIO_PIN_RESET = 0x00U,
    GPIO_PIN_SET
} GPIO_PinState_t;

/**
 * @brief 状态定义
 */
typedef enum {
    HAL_OK = 0x00U,
    HAL_ERROR,
    HAL_BUSY,
    HAL_TIMEOUT
} HAL_Status_t;

/* 不要写成这样, 成员不换行 */
typedef enum {
    HAL_OK = 0x00U, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT
} HAL_Status_t;

/**
 * @brief HAL写入GPIO电平
 * 
 * @param GPIOx GPIO端口
 * @param GPIO_Pin GPIO引脚
 * @param PinState 写入电平
 * @return `HAL_Status_t` 是否写入成功
 * @note 实际HAL库逻辑并非这样, 只是举个例子
 */
HAL_Status_t HAL_GPIO_Write_Pin(GPIO_t *GPIOx, uint16_t GPIO_Pin,
                                GPIO_PinState_t PinState) {
    assert_param(IS_GPIO_PIN(GPIO_Pin));
    ...
    GPIOx->ODR = GPIO->IDR | (GPIO_PinState << GPIO_Pin);
    if (GPIOx->IDR == GPIOx->ODR) {
        return HAL_OK;
    } else {
        return HAL_ERROR
    }
}

/* 纯下标定义, 可以不用typedef定义名称 */
enum {
    LAST = 0x00U,
    NOW,
    NEXT
};
array[LAST] = ...;

int* p, q; /* 当这样声明的时候p是int指针, q是int变量, 相当于: int* p; int q; */
/* 所以采用下面的方式, 看起来统一 */
int *p, *q;

/* 不规范写法 */
#define USE_FOO 0
#define NOT_USE_BAR 1

#if NOT_USE_BAR

    #define IS_FOO
void foo(void);

#else  /* NOT_USE_BAR */

    #define IS_BAR
void bar(void);

#define LED0(x) \
    (x) ? HAL_GPIO_WritePin(LED0_PORT, LED0_PIN, GPIO_PIN_SET) \
        : HAL_GPIO_WritePin(LED0_PORT, LED0_PIN, GPIO_PIN_RESET)

#endif /* NOT_USE_BAR */

/* 规范写法 */
#define USE_FOO     0
#define NOT_USE_BAR 1

#if NOT_USE_BAR

#define IS_FOO
void foo(void);

#else  /* NOT_USE_BAR */

#define IS_BAR
void bar(void);
/* 最右边的反斜杠就是续行符, 右对齐 */
#define LED0(x)                                                                \
    (x) ? HAL_GPIO_WritePin(LED0_PORT, LED0_PIN, GPIO_PIN_SET)                 \
        : HAL_GPIO_WritePin(LED0_PORT, LED0_PIN, GPIO_PIN_RESET)

#endif /* NOT_USE_BAR */

/**
 * @arg         @attention  @author     @brief      @bug
 * @copyright   @date       @def        @defgroup   @details
 * @note        @param      @private    @public     @ref
 * @return      @retval     @see        @todo       @version
 * @warning
 */

/**
 * @file    commune.c
 * @author  Deadline039
 * @brief   通信代码
 * @version 0.1
 * @date    2023-11-05
 * @note    遥控器发送的数据帧都为8个字节, 开头统一为0xFF, 结尾统一为0xCC
 *          --------------------------------------------------------------------
 *          遥控器数据帧格式:
 *          0xFF, 0xAA(标识遥控器), x1, y1, x2, y2, keys, 0xCC
 *          --------------------------------------------------------------------
 *          握手数据帧格式:
 *          0xFF, 'h'(标识握手), 'e', 'l', 'l', 'o', 0x00, 0xCC
 *          主板回复格式
 *          'O', 'K', 0x00, 0xCC
 *          --------------------------------------------------------------------
 *          发送key数据帧格式
 *          0xFF, 0xFE(标识key), key, key, key, key, 0x00, 0xCC
 *          --------------------------------------------------------------------
 *          检查连接数据帧格式
 *          0xFF, 0xFF(标识检验), 0x00, 0x00, 0x00, 0x00, 0x00, 0xCC
 *          主板回复格式
 *          key, key, key, key, 0x00, 0xCC
 *******************************************************************************
 *          CHECK_CONNECT宏用来定义是否进行连接检查, 0为不使用; 1为使用
 *          如果不使用连接检查, 开机直接向主板发送遥控器数据
 *
 *          如果使用连接检查, 上电会持续发送握手数据帧, 等待主板回复OK
 *          主板回复后, 向主板发送一个32位的key, 这个key是随机生成的
 *          发送格式就是key数据帧格式
 *
 *          遥控器每发送20帧遥控器数据, 会发送一个检查连接数据帧,
 *          主板将key发送给遥控器, 遥控器进行校验. 如果错误, 提示连接出错
 */

/**
 * @brief Starts the TIM Input Capture measurement. 这里可以不与下面的retval对齐
 * @param htim TIM Input Capture handle
 * @param Channel TIM Channels to be enabled. This parameter can be one of the
 *                following values: (这里换行了, 与上一行开头对齐)
 *  @arg TIM_CHANNEL_1: TIM Channel 1 selected  开头与@param错开一个空格
 *  @arg TIM_CHANNEL_2: TIM Channel 2 selected
 *  @arg TIM_CHANNEL_3: TIM Channel 3 selected
 *  @arg TIM_CHANNEL_4: TIM Channel 4 selected
 * @retval HAL status
 * @note 注意12行和13行之间不应该有空格
 */
HAL_StatusTypeDef HAL_TIM_IC_Start(TIM_HandleTypeDef *htim, uint32_t Channel) {
    uint32_t tmpsmcr;
    /* 双斜杠仅在注释代码时使用 */
    // HAL_TIM_ChannelStateTypeDef channel_state = TIM_CHANNEL_STATE_GET(htim, Channel);
    // HAL_TIM_ChannelStateTypeDef complementary_channel_state = TIM_CHANNEL_N_STATE_GET(htim, Channel);

    /* Check the parameters */
    assert_param(IS_TIM_CCX_INSTANCE(htim->Instance, Channel));
    ...
    /* Return function status */
    return HAL_OK;
}

/**
 * @brief 根据传感器数据获取实际位置
 *
 * @param[out] real_x x位置指针
 * @param[out] real_y y位置指针
 */
void GetPosition(double* real_x, double* real_y) {
    *real_x = ...;
    *real_y = ...;
}

/**
 * @brief  TIM Clear Input Configuration Handle Structure definition
 */
typedef struct {
  uint32_t ClearInputState;      /*!< TIM clear Input state
                                      This parameter can be ENABLE or DISABLE */
  uint32_t ClearInputSource;     /*!< TIM clear Input sources
                                      This parameter can be a value of @ref TIM_ClearInput_Source */
  uint32_t ClearInputPolarity;   /*!< TIM Clear Input polarity
                                      This parameter can be a value of @ref TIM_ClearInput_Polarity */
  uint32_t ClearInputPrescaler;  /*!< TIM Clear Input prescaler
                                      This parameter must be 0: When OCRef clear feature is used with ETR source, 
                                      ETR prescaler must be off */
  uint32_t ClearInputFilter;     /*!< TIM Clear Input filter
                                      This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF */
} TIM_ClearInputConfigTypeDef;

/**
 * @defgroup Moudle 1
 * @{
 */

...    

/**
 * @}
 */

/* 也可以加一堆*来区分, 一行80个字符 */
/*******************************************************************************
 * @defgroup Moudle 2
 * @{
 */

...

/**
 * @}
 ******************************************************************************/

/* 注释应该在这里 */
event_val |= event_bit;  /* 或者注释在这里 */
/* 不应该在这里注释 */

/* 这是说明第7行代码的注释, 第6行不应该空 */

event_val <<= 1;

/**
 * @todo 此处判断逻辑应该优化
 */
if ((event_val & 0x01) && !(event_val & 0x02)
    || !(event_val & 0x04) && (event_val & 0x08)) {
    ...
}

/**
 * @bug 这里的断言有时候会失效
 */
if (!event_val_assert(event_val)) {
    ...
}