注释风格

一、前言

注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在20%以上。

注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁，注释不宜太多也不能太少，注释的内容要清楚、明了、含义准确，防止注释二义性，该加的地方一定要加，但不必要的地方一定不要加。

注释风格很多，这里只是对于我的代码进行规范。

二、风格

1、文件注释

• FileName 文件名
• Description 模块描述
• Change Logs 变更日志

/*
 * Copyright (C), 1988-1999, Xxxxxx Tech. Co., Ltd.
 * FileName: xxx
 * Description: balabalabalabalabalabalabalabalabala
    balabalabalabalabalabalabalabalabalabalabalabala
 * Change Logs: 
    |Date           |Author       |Notes     |version
    |2010-03-22     |XXX          |XXX       |1.0.0
 */

2、函数注释

• Function 函数名称
• Description 函数描述
• Calls 调用的函数清单
• Input 输入参数说明，包括每个参数的作用、取值说明及参数间关系
• Output 输出参数的说明
• Return 函数返回值的说明
• Others 其他说明

/*
 * Function:
 * Description:
 * Calls:
 * Input:
 * Input:
 * Output:
 * Return:
 * Others:
 */

3、宏定义注释

• @define 定义块概述
• No error 定义值说明

/* @define xxx */
#define XXX_ERROR_OK              0   /* No error           */
#define XXX_ERROR_INVALID_TOKEN   1   /* Invalid token      */
#define XXX_ERROR_EXPECT_TYPE     2   /* Expect a type      */

4、结构体注释

• @struct 结构体概述
• next item 结构体元素说明

/* @struct xxx */
struct xxx_syscall_item
{
    struct xxx_syscall_item* next;    /* next item */
    struct xxx_syscall syscall;       /* syscall */
};

5、全局变量

全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

• Description 作用描述
• Scope 作用域
• Range 取值范围
• Notice 注意事项
• Others 其他说明

/*
 * Description:
 * Scope:
 * Range:
 * Notice:
 * Others:
 */