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

编程入门行业动态更新时间:2024-10-23 19:26:06

工程代码模板<a href=https://www.elefans.com/category/jswz/34/1770285.html style= 注释及C规范"/>

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

工程代码模板注释规范

效果
使用方法以IAR为例
C代码规范
- 工程注释模板
- - C文件模板
  - h文件模板
  - 函数注释
- 函数或变量命名方式
- 文件编码
- 对齐方式
- 优化
- 防御性编程
完成！

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>.**  @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/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>.",&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>.**  @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>.",&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 {  //处理错误代码  }  
}

完成！

更多推荐

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

本文发布于:2024-02-27 04:57:38，感谢您对本站的认可！

本文链接:https://www.elefans.com/category/jswz/34/1705257.html

注释模板代码工程

发布评论取消回复

评论列表（有 0 条评论）

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

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

工程代码模板注释规范

效果

使用方法以IAR为例

C代码规范

工程注释模板

C文件模板

h文件模板

函数注释

函数或变量命名方式

文件编码

对齐方式

优化

防御性编程

完成！

发布评论取消回复

最近发表

热门文章

标签列表