【C/C++ 基本知识注释规范】C/C++中注释方式以及规范

本文链接：https://blog.csdn.net/qq_21438461/article/details/125595869

目录标题

多行注释
单行注释
预处理形式注释
注释风格
文件注释
函数注释
变量注释
结语

注释是编译器忽略但对于程序员非常有用的文本。注释通常用于批注代码以供将来参考。在C/C++中，使用注释有三种方法。

多行注释

注释以 /* 开始，以 */ 终止：

单行注释

注释也能以 // 开始，直到行末为止。：

预处理形式注释

使用 #if 0 … #endif 来实现注释，可以实现嵌套：

#if 0

code

#endif

你可以把 #if 0 改成 #if 1 来执行 code 的代码。
这种形式对程序调试也可以帮助，测试时使用 #if 1 来执行测试代码，发布后使用 #if 0 来屏蔽测试代码。
#if 后可以是任意的条件语句

注释风格

总述

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

说明

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

文件注释

总述

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

说明

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

文件内容

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

函数注释

总述

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

说明

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

函数定义

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

变量注释

总述

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

说明

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

结语

在我们的编程学习之旅中，理解是我们迈向更高层次的重要一步。然而，掌握新技能、新理念，始终需要时间和坚持。从心理学的角度看，学习往往伴随着不断的试错和调整，这就像是我们的大脑在逐渐优化其解决问题的“算法”。

这就是为什么当我们遇到错误，我们应该将其视为学习和进步的机会，而不仅仅是困扰。通过理解和解决这些问题，我们不仅可以修复当前的代码，更可以提升我们的编程能力，防止在未来的项目中犯相同的错误。

我鼓励大家积极参与进来，不断提升自己的编程技术。无论你是初学者还是有经验的开发者，我希望我的博客能对你的学习之路有所帮助。如果你觉得这篇文章有用，不妨点击收藏，或者留下你的评论分享你的见解和经验，也欢迎你对我博客的内容提出建议和问题。每一次的点赞、评论、分享和关注都是对我的最大支持，也是对我持续分享和创作的动力。