注释原则

1. 项目开发中，尽量保持代码注释规范和统一。
2. 注释方便了代码的阅读和维护。
3. 边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。
4. 注释要简洁明确，不要出现形容词。
5. 通过注释可以快速知道所写函数的功能，返回值，参数的使用。

我们以C语言代码为例子进行注释学习。

文件头部注释

/********************************************************************************
* @File name: demo.c
* @Author: WangRongsheng
* @Version: 1.0
* @Date: 2020-3-10
* @Description: test.
********************************************************************************/

还可以增加：版权说明等。

如果你进行了代码的修改 ，你需要重新写注释：

/********************************************************************************
* @File name: demo.c
* @Author: WangRongsheng
* @Version: 1.0
* @Date: 2020-3-10
* @Description: test.

* @Modifier（修改人）：张三
* @Modification time（修改时间）：2001-02-16
* @Modify content（修改内容）：新增
********************************************************************************/

结构体、全局变量等的注释

    int num; /*全局变量的作用*/

    /*结构体的功能*/
    typedef struct{
        int h; /*High risk*/
        int l; /*Low risk*/
        int m; /*Middle risk*/
        int i; /*Information risk*/
    }risk;

函数注释

函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等

/*******************************************************
*
* 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)
{
    /*
    *    如果程序过于复杂，这里可以写明，具体算法和思路。
    */
}

建议

1. 一般情况下，源程序有效注释量必须在20％以上。 注释不宜太多、不宜太少，准确易懂简洁；

2. 注释格式尽量统一，建议使用“/* …… */”；

3. 避免在一行代码或表达式的中间插入注释；

说明：除非必要，不应在代码或表达中间插入注释， 否则容易使代码可理解性变差。

4. 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。

说明：清晰 准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

5. 在代码的功能、意图层次上进行注释，提供有用、额外的信息。

说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。