工程代码模板注释及C规范


Doxygen全套工具下载

效果

.chm文件
在这里插入图片描述

网页效果
在这里插入图片描述

使用方法以IAR为例

此模板符合Doxygen的注释规范,可以直接生成API文档,目前多数厂家的API文档皆是使用此规范进行注释。

1、按照下图路径打开编辑模板
在这里插入图片描述
2、复制以下模板内容填入即可

################################################################################
##
## This is an example file for defining your own code templates.
##
## The syntax for defining a code template is:
## #TEMPLATE <template name>,<field>[=default value], <field>...
##
## The template name, the fields and their default values should be defined 
## within quotes if they contain non-alphanumeric characters.
## Use "&" in front of a letter in the template name to make the letter become 
## a shortcut, which means that you can use ALT+<letter> to select the template 
## or jump to the field in the dialog box.
## Use ">" in the template to organize the template names in submenus.
##
################################################################################
#TEMPLATE "&Statement>&if"
if( %c )
{
  
}
#TEMPLATE &Statement>&for,"&End Value"=10,&Variable=i
for(int %2 = 0; %2 < %1; ++%2)
{
  %c
}
#TEMPLATE &Corporate>&class,"Class &name",&Description=--,&Created="$DATE$, by $USER_NAME$"
//******************
// CLASS: %1
//
// DESCRIPTION:
//  %2
//
// CREATED: %3
//
// FILE: $FILE_FNAME$
//
class %1
{
public:
  %1();
  ~%1();
  %c
};
/******************************** End of file *********************************/

#TEMPLATE &DoxygenComment>&_C_file_comment,"Author name"=aron566,&Description=--,&Created="$DATE$, by $USER_NAME$",&Version=v1.0
/**
 *  @file $FILE_FNAME$
 *
 *  @date $DATE$
 *
 *  @author %1
 *
 *  @copyright Copyright (c) 2021 aron566 <aron566@163.com>.
 *
 *  @brief %2
 *
 *  @details None.
 *
 *  @version %4
 *
    @verbatim
    ==============================================================================
                      ##### How to use this driver #####
    ==============================================================================
      [..]
        The PCD HAL driver can be used as follows:
    
       (#) Declare a PCD_HandleTypeDef handle structure, for example:
           PCD_HandleTypeDef  hpcd;
    
       (#) Fill parameters of Init structure in HCD handle
    
       (#) Call HAL_PCD_Init() API to initialize the PCD peripheral (Core, Device core, ...)
    
       (#) Initialize the PCD low level resources through the HAL_PCD_MspInit() API:
           (##) Enable the PCD/USB Low Level interface clock using
                (+++) __HAL_RCC_USB_CLK_ENABLE(); For USB Device only FS peripheral
    
           (##) Initialize the related GPIO clocks
           (##) Configure PCD pin-out
           (##) Configure PCD NVIC interrupt
    
       (#)Associate the Upper USB device stack to the HAL PCD Driver:
           (##) hpcd.pData = pdev;
    
       (#)Enable PCD transmission and reception:
           (##) HAL_PCD_Start();
    
    @endverbatim
    ******************************************************************************
    * @attention
    *
    * <h2><center>&copy; Copyright (c) 2016 xxxco.Lto.
    * All rights reserved.</center></h2>
    *
    * This software component is licensed by xxx under BSD 3-Clause license,
    * the "License"; You may not use this file except in compliance with the
    * License. You may obtain a copy of the License at:
    *                        opensource.org/licenses/BSD-3-Clause
    *
    ******************************************************************************
 */
/** Includes -----------------------------------------------------------------*/
/* Private includes ----------------------------------------------------------*/
#include "$FILE_FNAME$%c"
/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private typedef ----------------------------------------------------------*/

/** Private macros -----------------------------------------------------------*/

/** Private constants --------------------------------------------------------*/
/** Public variables ---------------------------------------------------------*/
/** Private variables --------------------------------------------------------*/

/** Private function prototypes ----------------------------------------------*/
/** @defgroup $FILE_FNAME$_Private_Functions $FILE_FNAME$ Private Functions
  * @{
  */
static void $FILE_FNAME$();
/**
  * @}
  */
/** Private user code --------------------------------------------------------*/
/**
 * @defgroup modulename $FILE_FNAME$
 * @{
 */
static void xx(void);
/** @}*/

/** Private application code -------------------------------------------------*/
/*******************************************************************************
*
*       Static code
*
********************************************************************************
*/

/** Public application code --------------------------------------------------*/
/*******************************************************************************
*
*       Public code
*
********************************************************************************
*/
#ifdef __cplusplus ///<end extern c
}
#endif
/******************************** End of file *********************************/

#TEMPLATE &DoxygenComment>&_H_file_comment,"Author name"="Copyright (c) 2021 aron566 <aron566@163.com>.",&Description=--,&Created="$DATE$, by $USER_NAME$",&Version=v1.0
/**
 *  @file $FILE_FNAME$
 *
 *  @date $DATE$
 *
 *  @author %1
 *
 *  @brief %2
 *  
 *  @version %4
 */
#ifndef $FILE_FNAME$%c
#define $FILE_FNAME$
/** Includes -----------------------------------------------------------------*/
#include <stdint.h> /*need definition of uint8_t*/
#include <stddef.h> /*need definition of NULL*/
//#include <stdbool.h>/*need definition of BOOL*/
#include <stdio.h>  /*if need printf*/
#include <stdlib.h>
#include <string.h>
#include <limits.h>/**< if need INT_MAX*/
/** Private includes ---------------------------------------------------------*/

/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private defines ----------------------------------------------------------*/
/**
 * @name 分组说明文字
 * @{
 */
#define xxx "sss"
/** @}*/
/** Exported typedefines -----------------------------------------------------*/
/** 数据结构体*/
typedef struct xx
{
    xx; /**< 说明 */
}xxx_t;
/** Exported constants -------------------------------------------------------*/

/** Exported macros-----------------------------------------------------------*/
/** Exported variables -------------------------------------------------------*/
/** Exported functions prototypes --------------------------------------------*/

#ifdef __cplusplus ///<end extern c
}
#endif
#endif
/******************************** End of file *********************************/

#TEMPLATE &DoxygenComment>&_DefineGroup_comment,&GROUPNAME=组名,"Macro"=XX,&Value=--
/**
 * @name %1
 * @{
 */
#define %2          (%3U)
/** @}*/

#TEMPLATE &DoxygenComment>&_Struct_comment,&Brief=描述 ,&STRUCTNAME=结构名
/** 数据结构体*/
/** 
  * @brief  %1  
  */  
typedef struct %2
{
    xx; /**< 说明 */
}%2_t;

#TEMPLATE &DoxygenComment>&_DefineGroup_comment,&Brief=描述 ,&DefineName=宏名,&Value=值
/** 宏定义*/
/** @defgroup %1
  * @{
  */ 
#define %2      %3
/**
  * @}
  */
  
#TEMPLATE &DoxygenComment>&Small_FUNC_comment,"Author name"=aron566,&Brief=--,&Created="$DATE$",&Version=v1.0
/**
  ******************************************************************
  * @brief   %2
  * @param   [in]None
  * @return  TRUE  成功
  * @return  FALSE 失败
  * @author  %1
  * @version %4
  * @date    $DATE$
  ******************************************************************
  */
static void %c(void)
{
    return;
}
#TEMPLATE &DoxygenComment>&Small+_FUNC_comment,"Author name"=aron566,&Brief=--,&Created="$DATE$",&Version=v1.0,&note=None
/************************************************************
  * @brief   %2
  * @param   [in]None
  * @param   [out]None
  * @pre     前置条件
  * @return  返回写入值
  *- -1表示写入文件失败
  * @author  %1
  * @date    $DATE$
  * @version %4
  * @note    %5
  ***********************************************************/
static void %c(void)
{
    return;
}

#TEMPLATE &DoxygenComment>&FULL_FUNC_comment,"Author name"=aron566,&Brief=--,&Created="$DATE$",&Version=v1.0,&note=None
/************************************************************
  * @brief   %2
  * @param   [in]None
  * @param   [out]None
  * @pre     前置条件
  * @return  返回写入值
  *- -1表示写入文件失败
  * @par     示例:
  * @code
  //示例代码
  int a = getlen(xx);
  * @endcode
  * @author  %1
  * @date    $DATE$
  * @version %4
  * @note    %5
  ***********************************************************/
static void %c(void)
{
    return;
}

#TEMPLATE &DoxygenComment>&Deprecated_FUNC_comment,"Author name"=aron566,&Brief=--,&Created="$DATE$",&Version=v1.0,&note=None
/************************************************************
  * @brief   %2
  * @param   [in]None
  * @param   [out]None
  * @pre     前置条件
  * @return  返回写入值
  *- -1表示写入文件失败
  *-# 带序号说明
  * @see     参考函数::openfile
  * @author  %1
  * @date    $DATE$
  * @version %4
  * @note    %5
  * @deprecated 此函数将在未来版本中取消
  ***********************************************************/
static void %c(void)
{
    return;
}

## C文件注释
#TEMPLATE &DoxygenREF>&C_file_comment,"Author name"=aron566,&Description=None,&Created="$DATE$, by $USER_NAME$",&Version=v1.0
/**
 *  @file $FILE_FNAME$
 *
 *  @date $DATE$
 *
 *  @author %1
 *
 *  @copyright Copyright (c) 2021 aron566 <aron566@163.com>.
 *
 *  @brief %2
 *
 *  @details 使用该模块有哪些细节注意等
 *
 *  @version %4
 */
/** Includes -----------------------------------------------------------------*/
/* Private includes ----------------------------------------------------------*/
#include "$FILE_FNAME$%c"
/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private typedef ----------------------------------------------------------*/

/** Private macros -----------------------------------------------------------*/

/** Private constants --------------------------------------------------------*/
/** Public variables ---------------------------------------------------------*/
/** Private variables --------------------------------------------------------*/

/** Private function prototypes ----------------------------------------------*/

/** Private user code --------------------------------------------------------*/
/**
 * @defgroup modulename $FILE_FNAME$
 * @{
 */
static void xx(void);
/** @}*/

/** Private application code -------------------------------------------------*/
/*******************************************************************************
*
*       Static code
*
********************************************************************************
*/

/** Public application code --------------------------------------------------*/
/*******************************************************************************
*
*       Public code
*
********************************************************************************
*/
#ifdef __cplusplus ///<end extern c
}
#endif
/******************************** End of file *********************************/

## H文件注释
#TEMPLATE &DoxygenREF>&H_file_comment,"Author name"="Copyright (c) 2021 aron566 <aron566@163.com>.",&Description=None,&Created="$DATE$, by $USER_NAME$",&Version=v1.0
/**
 *  @file $FILE_FNAME$
 *
 *  @date $DATE$
 *
 *  @author %1
 *
 *  @brief %2
 *  
 *  @version %4
 */
#ifndef $FILE_FNAME$%c
#define $FILE_FNAME$
/** Includes -----------------------------------------------------------------*/
#include <stdint.h> /*need definition of uint8_t*/
#include <stddef.h> /*need definition of NULL*/
//#include <stdbool.h>/*need definition of BOOL*/
#include <stdio.h>  /*if need printf*/
#include <stdlib.h>
#include <string.h>
#include <limits.h>/**< if need INT_MAX*/
/** Private includes ---------------------------------------------------------*/

/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private defines ----------------------------------------------------------*/
/**
 * @name 分组说明文字
 * @{
 */
#define xxx "sss"
/** @}*/
/** Exported typedefines -----------------------------------------------------*/
/** 数据结构体*/
typedef struct xx
{
    xx; /**< 说明 */
}xxx_t;
/** Exported constants -------------------------------------------------------*/

/** Exported macros-----------------------------------------------------------*/
/** Exported variables -------------------------------------------------------*/
/** Exported functions prototypes --------------------------------------------*/

#ifdef __cplusplus ///<end extern c
}
#endif
#endif
/******************************** End of file *********************************/

## 函数注释
#TEMPLATE &DoxygenREF>&FUNC_comment,"FUNC name"=None,&Brief=None,&Details=None,&attention=None,&note=None
/**
  ******************************************************************
  * @fn %1
  * @brief %2
  * @details %3
  * @param[in] 参数名 参数注解
  * @param[out] 参数名 参数注解
  * @param[in, out] 参数名 参数注解
  * @return None (宏函数无返回值)
  * @return 对返回值的说明
  * @see 扇入:调用了该函数的上级函数(扇入高表示该函数复用性好)
  * @see 扇出:该函数里调用了哪些下级函数(扇出高表示该函数复杂度高)
  * @note %5
  * @attention %4
  * @par example:
  * @code
  //代码示例
  * @endcode
  ******************************************************************
  */
static%c void %1(void)
{
    return;
}

## 枚举注释
#TEMPLATE &DoxygenREF>&Enum_comment,"Enum name"=None,&Brief=None,&Details=None,&attention=None,&note=None
/**
  ******************************************************************
  * @enum %1
  * @brief %2
  * @details %3
  * @note %5
  * @attention %4
  ******************************************************************
  */
typedef enum %1
{
    %c
}%1TypeDef;

## 宏函数注释
#TEMPLATE &DoxygenREF>&Define_comment,"Define name"=None,&Brief=None,&Details=None,&attention=None,&note=None
/**
  ******************************************************************
  * @def %1
  * @brief %2
  * @details %3
  * @param[in] 参数名 参数注解
  * @param[out] 参数名 参数注解
  * @param[in, out] 参数名 参数注解
  * @return None (宏函数无返回值)
  * @see 扇入:调用了该函数的上级函数(扇入高表示该函数复用性好)
  * @see 扇出:该函数里调用了哪些下级函数(扇出高表示该函数复杂度高)
  * @note %5
  * @attention %4
  * @par example:
  * @code
  //代码示例
  * @endcode
  ******************************************************************
  */
#define %1

## 结构体注释
#TEMPLATE &DoxygenREF>&Struct_comment,"Struct name"=None,&Brief=None,&Details=None,&attention=None,&note=None
/**
  ******************************************************************
  * @struct %1
  * @brief %2
  * @details %3
  * @note %5
  * @attention %4
  ******************************************************************
  */
typedef struct %1
{
    %c
}%1TypeDef;

## 联合体注释
#TEMPLATE &DoxygenREF>&Union_comment,"Union name"=None,&Brief=None,&Details=None,&attention=None,&note=None
/**
  ******************************************************************
  * @union %1
  * @brief %2
  * @details %3
  * @note %5
  * @attention %4
  ******************************************************************
  */
typedef union %1
{
    %c
}%1TypeDef;

C代码规范

工程注释模板

  • keil下注意保留文件最后空行,否者编译出现警告
  • 语句完整性要求:
    • if语句需带有花括号完整包含条件语句
    • 不带参数的函数使用void说明禁止参数表为空
  • 同行注释使用: /**< 注释语句*/
  • 尽可能的使用/* 注释 */ 对执行逻辑的注释,而不是//
  • 空格要求:声明或者定义函数时,其括号内参数以 数据类型+空格+参数名+逗号+空格…

C文件模板

/**
 *  @file xxx.c
 *
 *  @date 2021-02-7
 *
 *  @author aron566
 *
 *  @copyright None.
 *
 *  @brief 
 *
 *  @details 1、
 *
 *  @version V1.0
 */
/** Includes -----------------------------------------------------------------*/
/* Private includes ----------------------------------------------------------*/
#include "xx.h"

/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private typedef ----------------------------------------------------------*/
/** Private macros -----------------------------------------------------------*/
/** Private constants --------------------------------------------------------*/
/** Public variables ---------------------------------------------------------*/
/** Private variables --------------------------------------------------------*/

/** Private function prototypes ----------------------------------------------*/

/** Private user code --------------------------------------------------------*/
/**
 * @defgroup modulename $FILE_FNAME$
 * @{
 */
static void xx(void);
/** @}*/

/** Private application code -------------------------------------------------*/
/*******************************************************************************
*
*       Static code
*
********************************************************************************
*/
/**
  ******************************************************************
  * @brief   
  * @param   [in]None
  * @return  TRUE  成功
  * @return  FALSE 失败
  * @author  aron566
  * @version V1.0
  * @date    2021-01-25
  ******************************************************************
  */
/** Public application code --------------------------------------------------*/
/*******************************************************************************
*
*       Public code
*
********************************************************************************
*/
#ifdef __cplusplus ///<end extern c
}
#endif
/******************************** End of file *********************************/

h文件模板

/**
 *  @file xxx.h
 *
 *  @date 2021-01-25
 *
 *  @author aron566
 *
 *  @brief 
 *  
 *  @version V1.0
 */
#ifndef $FILE_FNAME$%c
#define $FILE_FNAME$
/** Includes -----------------------------------------------------------------*/
#include <stdint.h> /**< need definition of uint8_t */
#include <stddef.h> /**< need definition of NULL    */
#include <stdbool.h>/**< need definition of BOOL    */
#include <stdio.h>  /**< if need printf             */
#include <stdlib.h>
#include <string.h>
#include <limits.h> /**< need variable max value    */
/** Private includes ---------------------------------------------------------*/

/* Use C compiler ------------------------------------------------------------*/
#ifdef __cplusplus ///< use C compiler
extern "C" {
#endif
/** Private defines ----------------------------------------------------------*/
/**
 * @name 分组说明文字
 * @{
 */
#define xxx "sss"
/** @}*/
/** Exported typedefines -----------------------------------------------------*/
/*枚举*/
typedef enum
{
    XXXXX = 0,
    
}XX_Typedef_t
    
/** 数据结构体*/
typedef struct
{
    xx; /**< 说明 */
}xxx_Typedef_t;

/** Exported constants -------------------------------------------------------*/

/** Exported macros-----------------------------------------------------------*/
/** Exported variables -------------------------------------------------------*/
/** Exported functions prototypes --------------------------------------------*/

#ifdef __cplusplus ///<end extern c
}
#endif
#endif
/******************************** End of file *********************************/

函数注释

/**
  ******************************************************************
  * @brief   %2
  * @param   [in]None
  * @return  TRUE  成功
  * @return  FALSE 失败
  * @author  aron566
  * @version v1.0
  * @date    2021-5-28
  ******************************************************************
  */
static void xxx(void)
{
    return;
}

函数或变量命名方式

  • 函数:大驼峰+下划线方式:void Get_Val(void) 在Linux中是以小写+下划线方式:void get_val(void);

  • 宏定义枚举:皆使用大写

  • 重命名: 大写字母_Typedef_t

文件编码

  • 编码是使用UTF-8编码无BOM

对齐方式

  • TAB键一般使用4空格缩进,但是设置2个空格感觉更好,按下两次tab

优化

  • 全局变量尽可能少,局部变量皆使用static关键字声明
  • 需对外的函数接口函数或者类型定义声明到头文件,否则应为对应c文件的私有
  • 传参,无需修改内容的指针传递需使用const声明如:void xx(const int *arry);
  • 返回,不可被外部修改的返回值需使用const声明如:const int *Get_Arry_Addr(void);
  • 类型转换,在不同的类型转换中使用显式的类型转换如:uint16_t ff = 11; int xx = (int)ff;
  • 宏定义,在定义数值时使用带U后缀显式说明这是无符号数,带有运算符的宏必需使用括号
  • 指针的操作,如在*p++语法中需使用括号明确指定语句优先级
  • 对于while(1)语句和for(;;)语句,优先使用for
  • 在基本数据类型中优先使用标准库中<stdint.h>中的数据类型,如:uint8_t int8_t uint16_t uint32_t,在uint64_t在32位和64位中长度不同,它会是平台支持的最大长度类型
  • 在字符串拷贝中优先使用带长度限定的接口,如strncpy显示指定最大拷贝长度
  • 在内存复制中优先使用memmove替代memcpy
  • 在堆内存申请中优先使用calloc替代malloc

防御性编程

在速度要求和代码精简要求不是太高的情况下应注重对参数的判断和临界值的限定。

  • 对入参的判断,防止访问无效内存区域
  • 对数组操作,防止越界访问
  • 声明局部变量定义明确初始化赋值
int exam_fun( unsigned char *str )   
{   
      if( str != NULL )     //  检查“假设指针不为空”这个条件 
	     {   
           //正常处理代码               
      } 
      else 
      {  
          //处理错误代码  
     }  
}

完成!

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

aron566

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值