嵌入式代码规范

一、注释部分：

每个文件应包含注释及对应版本，描述参考下面代码块

/********************************************************************************
 * Copyright (C) 2024 Alanla, Inc.(Gmbh) or its affiliates.
 *
 * All Rights Reserved.
 *
 * @file ec_bsp_aht21_driver.h
 *
 * @par dependencies
 * - ec_bsp_aht21_reg.h
 * - stdio.h
 * - stdint.h
 *
 * @author Alanla 
 *
 * @brief Provide the HAL APIs of AHT21 and corresponding opetions.
 *
 * Processing flow:
 *
 * call directly.
 *
 * @version V1.0 2023-12-03
 *
 * @note 1 tab == 4 spaces!
 *
 ********************************************************************************/

二、头文件包含部分

#ifndef __EC_BSP_AHT21_DRIVER_H__  //Avoid repeated including same files later
#define __EC_BSP_AHT21_DRIVER_H__

//**************************** Includes ****************************//

#include "ec_bsp_aht21_reg.h"      // 包含自己的寄存器.h文件一定是在最开始

#include <stdint.h>                // 编译器提供的通用库包含部分
#include <stdio.h>

//**************************** Includes ****************************//

三、定义与枚举部分

//**************************** Defines ****************************//
#define OS_SUPPORTING

/*  函数返回状态枚举              */
typedef enum
{
    AHT21_OK              = 0,        /* Operation completed successfully.  */
    AHT21_ERROR           = 1,        /* Run-time error without case matched*/
    AHT21_ERRORTIMEOUT    = 2,        /* Operation failed with timeout      */
    AHT21_ERRORRESOURCE   = 3,        /* Resource not available.            */
    AHT21_ERRORPARAMETER  = 4,        /* Parameter error.                   */
    AHT21_ERRORNOMEMORY   = 5,        /* Out of memory.                     */
    AHT21_ERRORISR        = 6,        /* Not allowed in ISR context         */
    AHT21_RESERVED        = 0x7FFFFFFF /* Reserved                          */
} aht21_status_t;

//**************************** Defines ****************************//

四、声明部分

//**************************** Declaring ****************************//

/* From Core层:   IIC 接口          */
#ifndef HARDWARE_IIC
typedef struct
{
    uint8_t (*pf_iic_init)        (void *);        // IIC初始化函数
    uint8_t (*pf_iic_deinit)      (void *);        // IIC反初始化函数
    void    (*pf_iic_start)       (void *);        // IIC起始信号函数
    void    (*pf_iic_stop)        (void *);        // IIC停止信号函数
    uint8_t (*pf_iic_wait_ack)    (void *);        // IIC等待确认信号
    void    (*pf_iic_send_ack)    (void *);        // IIC发送确认信号
    void    (*pf_iic_send_no_ack) (void *);        // IIC发送非确认信号
    void    (*pf_iic_send_byte)   (void *, uint8_t); // IIC发送一个字节
    uint8_t (*pf_iic_receive_byte)(void *);        // IIC接收一个字节

    void (*taskENTER_CRITICAL)(void);              // 进入临界区
    void (*taskEXIT_CRITICAL)(void);               // 退出临界区
}iic_driver_interface_t;
#endif //End of NO_HARDWARE_IIC

#ifdef HARDWARE_IIC
typedef struct
{
    uint8_t (*pf_iic_init)        (void *);        // IIC初始化函数
    uint8_t (*pf_iic_deinit)      (void *);        // IIC反初始化函数
    void    (*pf_iic_send_ack)    (void *);        // IIC发送确认信号
    void    (*pf_iic_send_no_ack) (void *);        // IIC发送非确认信号
    void    (*pf_iic_send_byte)(void *, uint8_t);  // IIC发送一个字节
    uint8_t (*pf_iic_receive_byte)(void *);        // IIC接收一个字节
}iic_driver_interface_t;
#endif //End of HARDWARE_IIC

/* From Core层:  时基系统          */
typedef struct
{
    uint32_t (*pf_get_tick_count)(void); // 获取系统tick数
}timebase_interface_t;

/* From OS层:  操作系统延时函数接口   */
#ifdef OS_SUPPORTING
typedef struct
{
    void (*rtos_yield)(const uint32_t);
}yield_interface_t;

#endif //End of OS_SUPPORTING

/*   aht21_hal_driver 实例对象结构体   */
typedef struct
{
    ....
}bsp_aht21_driver_t;

/*   aht21_hal_driver 构造函数        */
uint8_t aht21_inst(      bsp_aht21_driver_t *    const p_aht21_instance,
                         iic_driver_interface_t * const p_iic_driver_instance,
                         timebase_interface_t *    const p_timebase_instance,
                         yield_interface_t *      const p_yield_instance);

//**************************** Declaring ****************************//

#endif /* __EC_BSP_AHT21_DRIVER_H__ */

五、缩进

缩进规范

• 统一缩进 4 个空格

• 约定：1 Tab = 4 Spaces

变量命名规范（匈牙利命名法——下划线分隔）

• 除枚举和宏定义外，变量统一使用小写字母，不得出现大写字母

• 单词之间使用下划线 _ 分隔

枚举变量规范

• 枚举内部的枚举项：全部大写

• 枚举变量名：使用小写字母，并以 _t 结尾（typedef 定义的枚举类型统一以 _t 结尾）

规范示例对照

类型	正确示例	错误示例
普通变量	uint32_t sensor_tick;	uint32_t SensorTick;
枚举项	AHT21_OK	aht21_ok
枚举类型名	aht21_status_t	AHT21_Status

typedef enum
{
    AHT21_OK              = 0,        /* Operation completed successfully.  */
    AHT21_ERROR           = 1,        /* Run-time error without case matched*/
    AHT21_ERRORTIMEOUT    = 2,        /* Operation failed with timeout      */
    AHT21_ERRORRESOURCE   = 3,        /* Resource not available.            */
    AHT21_ERRORPARAMETER  = 4,        /* Parameter error.                   */
    AHT21_ERRORNOMEMORY   = 5,        /* Out of memory.                     */
    AHT21_ERRORISR        = 6,        /* Not allowed in ISR context         */
    AHT21_RESERVED        = 0x7FFFFFFF /* Reserved                          */
} aht21_status_t;

六、宏定义规范

• 命名规则：全部大写，单词之间用下划线 _ 分隔

• 代码示例：

#define OS_SUPPORTING
#define AHT21_MEASURE_WAITING_TIME 80  /*测量等待时间，80ms */

七、全局变量规范

• 命名规则：统一以 g_ 开头，其余部分小写+下划线

• 代码示例：

static int8_t  g_inited     = 0;  /*初始化状态        */
static uint8_t g_device_id  = 0;  /*设备ID            */

八、局部变量规范

• 命名规则：无特殊需求时，使用小写+下划线格式

• 重要提醒：定义局部变量时必须赋初值

• 代码示例：

uint8_t byte_1th = 0;
//任何时候定义局部变量一定要赋初值！！！

九、指针变量规范

• 命名规则：指针变量统一以 p_ 开头

• 代码示例：

bsp_aht21_driver_t * p_aht21_instance = NULL;

十、函数指针变量规范

• 命名规则：函数指针变量统一以 pf_ 开头（pf = pointer function）

• 代码示例：

uint8_t (*pf_iic_init)(void *);

十一、函数调用规范

• 核心要求：任何函数调用后，必须判断其返回值，避免错误扩散

• 代码示例：

int8_t ret = 0;

ret = OS_QUEUE_CREATE(10, sizeof(xxx), &(xxx));
log_d("OS_QUEUE_CREATE ret=%d\r\n", ret);

if(ret)  // 判断返回值
{
#ifdef AHT21_HANDLER_DEBUG
    log_e("error:create queue fail!");
#endif
    return AHT21_ERRORRESOURCE;
}

十二、指针使用规范

• 核心要求：任何指针在使用前，必须先判断是否为空指针，避免空指针访问导致程序崩溃

• 代码示例：

p_handler_instance = NULL;
p_handler_instance = p_input_arg;

if(NULL == p_handler_instance)
{
    log_e("p_handler_instance is NULL");
    return AHT21_ERRORPARAMETER;
}

十三、相等判断规范

• 核心要求：使用 == 做相等判断时，必须把常量放在左边，防止误写为赋值运算符 =

• 代码示例：

if(0 == g_inited)
{
    return AHT21_ERRORRESOURCE;
}

十四、代码幅宽规范

• 核心要求：单行代码宽度不得超过80列，函数参数过长或条件判断式过长时，可换行拆分参数/条件

• 函数参数换行示例：

static uint8_t aht21_read_temp(bsp_aht21_driver_t * const paht21_instance,
                               float * const temp,
                               float * const humi);

• 条件判断换行示例：

log_d("aht21_init start");
if( NULL == paht21_instance->piic_driver_instance        ||
    NULL == paht21_instance->piic_driver_instance->pf_iic_init)
{
    log_e("piic_driver_instance is NULL");
}

十五、函数注释规范

• 核心要求：所有函数必须添加 Doxygen 风格注释，包含功能简述、步骤、参数、返回值等信息

• 代码示例：

/**
 * @brief Instantiates the bsp_led_handler_t target.
 *
 * Steps:
 *
 * 1. Adds Core interfaces into bsp_led_driver instance target.
 * 2. Adds OS interfaces into bsp_led_driver instance target.
 * 3. Adds timebase interfaces into bsp_led_driver instance target.
 *
 * @param[in] self        : Pointer to the target of handler.
 * @param[in] os_delay    : Pointer to the os_delay_interface.
 * @param[in] os_queue    : Pointer to the os_queue_interface.
 * @param[in] os_critical : Pointer to the os_critical_interface.
 * @param[in] os_thread   : Pointer to the os_thread_interface.
 * @param[in] time_base   : Pointer to the time_base_interface.
 *
 * @return led_handler_status_t : Status of the function.
 *
 */
led_handler_status_t led_handler_inst (
                               bsp_led_handler_t      * const      self,
#ifdef OS_SUPPORTING
                               os_delay_t             * const      os_delay,
                               handler_os_queue_t     * const      os_queue,
                               handler_os_critical_t  * const      os_critical,
                               handler_os_thread_t    * const      os_thread,
#endif //OS_SUPPORTING
                               handler_time_base_ms_t * const      time_base  );