【学习】“注释”建议若干

建议1.函数声明处注释描述函数功能、性能及用法，包括输入和输出参数、函数返回值、可重入的要求等；定义处详细描述函数功能和实现要点，如实现的简要步骤、实现的理由、设计约束等。

说明：重要的、复杂的函数，提供外部使用的接口函数应编写详细的注释。

建议2. 避免在注释中使用缩写，除非是业界通用或子系统内标准化的缩写。

建议3. 同一产品或项目组统一注释风格。

建议4.避免在一行代码或表达式的中间插入注释。

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

建议5.注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。对于有外籍员工的，由产品确定注释语言。

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。

建议6.文件头、函数头、全局常量变量、类型定义的注释格式采用工具可识别的格式。

说明：采用工具可识别的注释格式，例如doxygen格式，方便工具导出注释形成帮助文档。

以doxygen格式为例，文件头，函数和全部变量的注释的示例如下：

文件头注释：

/**

* @file （本文件的文件名eg：mib.h）

* @brief （本文件实现的功能的简述）

* @version 1.1 （版本声明）

* @author （作者，eg：张三）

* @date （文件创建日期，eg：2010年12月15日）

*/

函数头注释：

/**

*@ Description:向接收方发送SET请求

* @param req - 指向整个SNMP SET 请求报文.

* @param ind - 需要处理的subrequest 索引.

* @return 成功：SNMP_ERROR_SUCCESS，失败：SNMP_ERROR_COMITFAIL

*/

Int commit_set_request(Request *req, int ind);

函数头注释建议写到声明处。并非所有函数都必须写注释，建议针对这样的函数写注释：重要的、复杂的函数，提供外部使用的接口函数。

全局变量注释：

/** 模拟的Agent MIB */

agentpp_simulation_mib * g_agtSimMib;

参考：gitcode社区-开源文档-菊厂C编程规范