其他
C/C++编码规范:注释
关注+星标公众号,不错过精彩内容
编排 | strongerHuang
微信公众号 | 嵌入式专栏
嵌入式专栏
1
1.总述
一般使用 //
或 /* */
,只要统一就好。
2.说明
//
或 /* */
都可以,但 //
更 常用,要在如何注释及注释风格上确保统一。
嵌入式专栏
2
1.总述
如果一个 .h
文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 .h
和 .cc
之间复制注释, 这样的注释偏离了注释的实际意义。
嵌入式专栏
3
1.总述
不要 从 .h
文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
嵌入式专栏
4
1.总述
嵌入式专栏
5
1.总述
嵌入式专栏
6
1.总述
TODO
注释。TODO
注释要使用全大写的字符串 TODO
, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO
相关的 issue. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO
格式进行查找. 添加 TODO
注释并不意味着你要自己来修正, 因此当你加上带有姓名的 TODO
时, 一般都是写上自己的名字。嵌入式专栏
7
1.总述
DEPRECATED
comments)以标记某接口点已弃用.DEPRECATED
的注释, 以标记某接口为弃用状态. 注释可以放在接口声明前, 或者同一行.DEPRECATED
一词后, 在括号中留下您的名字, 邮箱地址以及其他身份标识.DEPRECATED
并不会让大家不约而同地弃用, 您还得亲自主动修正调用点(callsites), 或是找个帮手.嵌入式专栏
8
注释固然很重要, 但最好的代码应当本身就是文档,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!
------------ END ------------
点击“阅读原文”查看更多分享,欢迎点分享、收藏、点赞、在看。