初学编程要注重写注释，为你说明代码规范注释有哪些讲究

来自公众号：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 时, 通常都是写上本身的名字。

 

 

 

 

1.总述

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

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

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

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

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

修正好的代码应该不会再涉及弃用接口点了, 着实改用新接口点. 若是您不知从何下手, 能够找标记弃用注释的当事人一块儿商量。

 

结语

 

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

 

你写的注释是给代码阅读者看的, 也就是下一个须要理解你代码的人。因此慷慨些吧，下一个读者可能就是你！

 

若是你对C/C++感兴趣，想学编程，小编推荐一个C/C++技术交流群【点击进入】！

涉及到了：编程入门、游戏编程、网络编程、Windows编程、Linux编程、Qt界面开发、黑客等等......