1.注释原则
- 项目开发中,尽量保持代码注释规范和统一。
- 注释方便了代码的阅读和维护。
- 边写代码边注释,修改代码时要相应修改注释,保证注释和代码的一致性。
- 注释要简洁明确,不要出现形容词。
- 通过注释可以快速知道所写函数的功能,返回值,参数的使用。
2.文件头部注释
/********************************************************************************
* @File name: biu.c
* @Author: fangqw
* @Version: 1.1
* @Date: 2021-3-19
* @Description: The function interface。
********************************************************************************/
- 还可以增加:版权说明等。
3. 结构体、全局变量等的注释
int num; /*全局变量的作用*/
/*结构体的功能*/
typedef struct{
int h; /*High risk*/
int l; /*Low risk*/
int m; /*Middle risk*/
int i; /*Information risk*/
}risk;
4. 函数的注释
函数头部应进行注释,列出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等
/********************************************************
* Function name :insert_hhistory
* Description : Insert to bd_host_history
* Parameter :
* @ipsql SQL statement
* @host_level Risk level
* @total The total number of risk
* @t_id task id
* @t_uuid task uuid
* @ipaddr target ipaddr
* @end_time task end time
* Return :0 --success , other -- fail
**********************************************************/
int insert_hhistory(char* ipsql,risk host_level,int total,int t_id,char* t_uuid,char* ipaddr,long int end_time)
{
/*
* 如果程序过于复杂,这里可以写明,具体算法和思路。
*/
}
5. 建议
- 一般情况下,源程序有效注释量必须在20%以上。 注释不宜太多、不宜太少,准确易懂简洁;
- 注释格式尽量统一,建议使用“/* …… */”;
- 避免在一行代码或表达式的中间插入注释;
- 说明:除非必要,不应在代码或表达中间插入注释, 否则容易使代码可理解性变差。
- 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
- 清晰 准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
- 在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说 明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。