不要在 .h和 .cc之间复制注释, 这样的注释偏离了注释的实际意义。
strongerHuang
3
函数注释
1.总述
函数声明处的注释描述函数功能; 定义处的注释描述函数实现。
2.说明
函数声明：
基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数)。
比如：FreeRTOS创建任务函数申明：
函数定义：
如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释。比如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由. 举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要。
不要 从 .h文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
strongerHuang
4
变量注释
1.总述
通常变量名本身足以很好说明变量用途， 某些情况下, 也需要额外的注释说明。
2.说明
根据不同场景、不同修饰符，变量可以分为很多种类，总的来说变量分为全局变量、局部变量。
一般来说局部变量仅限于局部范围，其含义相对简单容易理解，只需要简单注释即可。
全局变量一般作用于多个文件，或者整个工程，因此，其含义相对更复杂，所以在注释的时候，最好描述清楚其具体含义，就是尽量全面描述。
（提示：全局变量尽量少用）
strongerHuang
5
拼写注释
1.总述
可能一个变量、一个函数包含的意思非常复杂，需要多个单词拼写而成，此时对拼写内容就需要详细注释。
2.说明
注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句. 大多数情况下, 完整的句子比句子片段可读性更高. 短一点的注释, 比如代码行尾注释, 可以随意点, 但依然要注意风格的一致性。
同时，注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有很大帮助。
strongerHuang
6
TODO 注释
1.总述
对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO注释。
TODO注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO相关的 issue. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO格式进行查找. 添加 TODO注释并不意味着你要自己来修正, 因此当你加上带有姓名的 TODO时, 一般都是写上自己的名字。
strongerHuang
7
TODO 注释
1.总述
通过弃用注释（DEPRECATEDcomments）以标记某接口点已弃用.
您可以写上包含全大写的 DEPRECATED的注释, 以标记某接口为弃用状态. 注释可以放在接口声明前, 或者同一行.
在 DEPRECATED一词后, 在括号中留下您的名字, 邮箱地址以及其他身份标识.
弃用注释应当包涵简短而清晰的指引, 以帮助其他人修复其调用点. 在 C++ 中, 你可以将一个弃用函数改造成一个内联函数, 这一函数将调用新的接口.
仅仅标记接口为 DEPRECATED并不会让大家不约而同地弃用, 您还得亲自主动修正调用点（callsites）, 或是找个帮手.
修正好的代码应该不会再涉及弃用接口点了, 着实改用新接口点. 如果您不知从何下手, 可以找标记弃用注释的当事人一起商量。
strongerHuang
8
结语
注释固然很重要, 但最好的代码应当本身就是文档，有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你！
免责声明：本文系网络转载，版权归原作者所有。如涉及作品版权问题，请与我们联系，我们将根据您提供的版权证明材料确认版权并支付稿酬或者删除内容。返回搜狐，查看更多