摩登3登录_C/C++代码规范注释有哪些讲究?

关注、星标公众,不错过精彩内容

编排 | strongerHuang
微信公众号:strongerHuang


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


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


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



strongerHuang

1

注释风格

1.总述

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

2.说明

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



strongerHuang

2

文件注释

1.总述

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


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


2.说明
法律公告和作者信息:
每个文件都应该包含许可证引用. 为项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。


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


3.文件内容

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

不要在 .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.总述

通过弃用注释(
DEPRECATED
 comments)以标记某接口点已弃用.
您可以写上包含全大写的 
DEPRECATED
 的注释, 以标记某接口为弃用状态. 注释可以放在接口声明前, 或者同一行.
在 
DEPRECATED
 一词后, 在括号中留下您的名字, 邮箱地址以及其他身份标识.
弃用注释应当包涵简短而清晰的指引, 以帮助其他人修复其调用点. 在 C++ 中, 你可以将一个弃用函数改造成一个内联函数, 这一函数将调用新的接口.
仅仅标记接口为 
DEPRECATED
 并不会让大家不约而同地弃用, 您还得亲自主动修正调用点(callsites), 或是找个帮手.
修正好的代码应该不会再涉及弃用接口点了, 着实改用新接口点. 如果您不知从何下手, 可以找标记弃用注释的当事人一起商量。


strongerHuang

8

结语

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


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



———— END ————


推荐阅读:
C语言实现面向对象的原理
无MMU抢占式操作系统的抢占工作原理




免责声明:本文内容由21ic获得授权后发布,版权归原作者所有,本平台仅提供信息存储服务。文章仅代表作者个人观点,不代表本平台立场,如有问题,请联系我们,谢谢!