浅析C++代码规范注释有哪些讲究？

作为一名合格的C++开发工程师，不仅需要了解清楚开发技术之外，还需要了解清楚C++注释的用法，这是因为注释虽然写起来很痛苦，但对保证代码可读性至关重要。

浅析C++代码规范注释有哪些讲究？

下面的将描述如何注释以及在哪儿注释。

注释风格：

1、总述：一般使用 // 或 /* */，只要统一就好。

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

文件注释：

1、总述：在每一个文件开头加入版权、作者、时间等描述。文件注释描述了该文件的内容，如果一个文件只声明，或实现，或测试了一个对象，并且这个对象已经在它的声明处进行了详细的注释，那么就没必要再加上文件注释，除此之外的其他文件都需要文件注释。

2、说明法律公告和作者信息：每个文件都应该包含许可证引用。为项目选择合适的许可证版本(比如： Apache2。0、BSD、LGPL、GPL)。如果你对原始作者的文件做了重大修改，请考虑删除原作者信息。

3、文件内容：如果一个。h 文件声明了多个概念，则文件注释应当对文件的内容做一个大致的说明，同时说明各概念之间的联系。一个一到两行的文件注释就足够了，对于每个概念的详细文档应当放在各个概念中，而不是文件注释中。不要在。h 和。cc 之间复制注释，这样的注释偏离了注释的实际意义。

浅析C++代码规范注释有哪些讲究？

函数注释：

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

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

函数定义：

如果函数的实现过程中用到了很巧妙的方式，那么在函数定义处应当加上解释性的注释。比如，你所使用的编程技巧，实现的大致步骤，或解释如此实现的理由。举个例子，你可以说明为什么函数的前半部分要加锁而后半部分不需要。不要从。h 文件或其他地方的函数声明处直接复制注释。简要重述函数功能是可以的，但注释重点要放在如何实现上。

浅析C++代码规范注释有哪些讲究？

变量注释：

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

2、说明根据不同场景、不同修饰符，变量可以分为很多种类，总的来说变量分为全局变量、局部变量。一般来说局部变量仅限于局部范围，其含义相对简单容易理解，只需要简单注释即可。全局变量一般作用于多个文件，或者整个工程，因此，其含义相对更复杂，所以在注释的时候，最好描述清楚其具体含义，就是尽量全面描述。（提示：全局变量尽量少用）。

拼写注释：

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

2、说明注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句。大多数情况下，完整的句子比句子片段可读性更高。短一点的注释，比如代码行尾注释，可以随意点，但依然要注意风格的一致性。同时，注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬，但清晰易读的代码还是很重要的。正确的标点，拼写和语法对此会有很大帮助。

TODO注释：

1、总述：对那些临时的，短期的解决方案，或已经够好但仍不完美的代码使用 TODO 注释。TODO 注释要使用全大写的字符串 TODO，在随后的圆括号里写上你的名字，邮件地址，bugID，或其它身份标识和与这一 TODO 相关的issue。主要目的是让添加注释的人(也是可以请求提供更多细节的人)可根据规范的 TODO 格式进行查找。添加 TODO 注释并不意味着你要自己来修正，因此当你加上带有姓名的 TODO 时，一般都是写上自己的名字。

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

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

免费领取C++学习资料

浅析C++代码规范注释有哪些讲究？相关推荐

C/C 代码规范注释有哪些讲究？
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事"删库跑路"了. 看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注 ...
给代码写注释时有哪些讲究？
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事"删库跑路"了. 看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注 ...
【编码规范篇】| C#编码规范代码规范总结，包括命名规范，代码规范注释规范等
数据开发的代码规范以及代码评审脚本
文章目录 1.概述 2.代码规范 2.1.通用代码规范 2.2.配置文件和传参规范 2.3.Python代码规范 2.4.SQL代码规范 2.5.其它 3.代码评审自动化脚本 4.数据逻辑校验机制 ...
java 注释超链接_java_Java代码注释规范详解，代码附有注释对程序开发者来 - phpStudy...
Java代码注释规范详解代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一在整个应 ...
c++ doxygen 注释规范_[代码规范]Go语言编码规范指导
本规范旨在为日常Go项目开发提供一个代码的规范指导,方便团队形成一个统一的代码风格,提高代码的可读性,规范性和统一性.本规范将从命名规范,注释规范,代码风格和 Go 语言提供的常用的工具这几个方面做一 ...
怎么解决缺少java.doc_阿里代码规范检测中方法缺少javadoc注释怎么办
阿里代码规范检测中方法缺少javadoc注释怎么办发布时间:2020-08-12 15:01:48 来源:亿速云阅读:204 作者:小新这篇文章给大家分享的是有关阿里代码规范检测中方法缺少jav ...
【Python基础学习笔记day05】pycharm注释的作用+单行注释（行注释）+多行注释（块注释）+关于代码规范
注释文章目录注释目标 01. 注释的作用 02. 单行注释(行注释) 在代码后面增加的单行注释 03. 多行注释(块注释) 什么时候需要使用注释? 关于代码规范目标注释的作用单行注释(行注 ...
c代码Doxygen注释规范
c代码Doxygen注释规范前言:良好得注释风格利于后期维护和团队协作开发,使得代码逻辑清晰,意图明了.Doxygen是一种能自动提取代码内注释生成版主文档的开源软件,它是跨平台的.非开源项目也许并 ...

浅析C++代码规范注释有哪些讲究？

浅析C++代码规范注释有哪些讲究？相关推荐

最新文章

热门文章