建议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编程规范
网友评论