C语言编码“注释”规范

Posted 2022-03-15 strongerHuang

关注+星标公众号，不错过精彩内容

编排 | strongerHuang

微信公众号 | 嵌入式专栏

如果领导给你一个项目的源码让你阅读，并理解重构代码，但里面一句注释都没有，我想这肯定是之前同事“删库跑路”了。

看一份源码什么很重要？除了各种代码规范之外，还有一个比较重要的就是注释。

注释虽然写起来很痛苦, 但对保证代码可读性至关重要，下面的将描述如何注释以及在哪儿注释。

注释风格

1.总述

一般使用 // 或 /* */，只要统一就好。

2.说明

// 或 /* */ 都可以，但 // 更 常用，要在如何注释及注释风格上确保统一。

文件注释

1.总述

在每一个文件开头加入版权、作者、时间等描述。

文件注释描述了该文件的内容，如果一个文件只声明，或实现，或测试了一个对象，并且这个对象已经在它的声明处进行了详细的注释，那么就没必要再加上文件注释，除此之外的其他文件都需要文件注释。

2.说明

法律公告和作者信息：

每个文件都应该包含许可证引用. 为项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。

如果你对原始作者的文件做了重大修改，请考虑删除原作者信息。

3.文件内容

如果一个 .h 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。

不要在 .h 和 .cc 之间复制注释, 这样的注释偏离了注释的实际意义。

函数注释

1.总述

函数声明处的注释描述函数功能; 定义处的注释描述函数实现。

2.说明

函数声明：

基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数)。

比如：FreeRTOS创建任务函数申明：

函数定义：

如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释。比如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由. 举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要。

不要 从 .h 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。

变量注释

1.总述

通常变量名本身足以很好说明变量用途， 某些情况下, 也需要额外的注释说明。

2.说明

根据不同场景、不同修饰符，变量可以分为很多种类，总的来说变量分为全局变量、局部变量。

一般来说局部变量仅限于局部范围，其含义相对简单容易理解，只需要简单注释即可。

全局变量一般作用于多个文件，或者整个工程，因此，其含义相对更复杂，所以在注释的时候，最好描述清楚其具体含义，就是尽量全面描述。

（提示：全局变量尽量少用）

拼写注释

1.总述

可能一个变量、一个函数包含的意思非常复杂，需要多个单词拼写而成，此时对拼写内容就需要详细注释。

2.说明

注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句. 大多数情况下, 完整的句子比句子片段可读性更高. 短一点的注释, 比如代码行尾注释, 可以随意点, 但依然要注意风格的一致性。

同时，注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有很大帮助。

TODO 注释

1.总述

对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释。

TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO 格式进行查找. 添加 TODO 注释并不意味着你要自己来修正, 因此当你加上带有姓名的 TODO 时, 一般都是写上自己的名字。

TODO 注释

1.总述

通过弃用注释（DEPRECATED comments）以标记某接口点已弃用.

您可以写上包含全大写的 DEPRECATED 的注释, 以标记某接口为弃用状态. 注释可以放在接口声明前, 或者同一行.

在 DEPRECATED 一词后, 在括号中留下您的名字, 邮箱地址以及其他身份标识.

弃用注释应当包涵简短而清晰的指引, 以帮助其他人修复其调用点. 在 C++ 中, 你可以将一个弃用函数改造成一个内联函数, 这一函数将调用新的接口.

仅仅标记接口为 DEPRECATED 并不会让大家不约而同地弃用, 您还得亲自主动修正调用点（callsites）, 或是找个帮手.

修正好的代码应该不会再涉及弃用接口点了, 着实改用新接口点. 如果您不知从何下手, 可以找标记弃用注释的当事人一起商量。

结语

注释固然很重要, 但最好的代码应当本身就是文档，有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。

你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你！

------------ END ------------

关注公众号回复“加群”按规则加入技术交流群，回复“1024”查看更多内容。

点击“阅读原文”查看更多分享。