为了提高我们写的代码的可读性,本文章说一下C/C++的编码规范。
一、源文件头部的注释
/*****************************************************************************
** Copyright © 2020 lcg. All rights reserved.
** File name: 文件名
** Description: 用于详细说明此程序文件完成的主要功能
** Author: 作者
** Version: 版本
** Date: 完成日期
*****************************************************************************/
二、函数的注释
/*!
@Function: 函数名称
@Description: 函数功能、性能等的描述
@Calls: 被本函数调用的函数清单
@Called By: 调用本函数的函数清单
@Table Accessed: 被访问的表(此项仅对于牵扯到数据库操作的程序)
@Table Updated: 被修改的表(此项仅对于牵扯到数据库操作的程序)
@Input: 输入参数说明,包括每个参数的作用、取值说明及参数间关系
@Output: 对输出参数的说明
@Return: 函数返回值的说明
@Others: 其它说明
*/
三、全局变量的注释
全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
/* Description1 */
/* Description2 */
int m_Global;
四、普通变量的注释
变量注释一个变量如果代表的意思不容易从变量名看出来,而且又挺重要的话最好也加点注释
int m_nGrowBy; // number of cache elements to grow by for new allocs
或者
int m_nGrowBy; /* number of cache elements to grow by for new allocs*/
五、结构体的注释
/*!
@brief 简要说明文字
*/
typedef struct 结构体名字 {
成员1, /*!< 简要说明文字 */
成员2, /*!< 简要说明文字 */
成员3, /*!< 简要说明文字 */
} 结构体别名;