给代码写注释时有哪些讲究？-技术圈

数学算法俱乐部

日期： 2021年02月17日

正文共：2051字

来源： strongerHuang


整理/来源：strongerHuang

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

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

注释虽然写起来很痛苦, 但对保证代码可读性至关重要，下面我们就以C/C++代码规范注释为例，将描述如何注释以及有哪些讲究。

注释风格

1. 总述

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

2. 说明

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

文件注释

1. 总述

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

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

2. 说明

法律公告和作者信息：

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

3. 文件内容

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

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

最后再举个最简单的实际例子：

/**************************************************************************    Copyright  Copyright 2020 Google Inc.*    File Name: 文件名*    Description: 描述**    Version: V1.0*    Author: Your_Name*    Create Time: 2020-01-01**************************************************************************/

函数注释

1. 总述

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

2. 说明

函数声明：

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

比如：

/**************************************************************************    函 数 名：函数名*    函数功能：功能描述*    输入参数：void*    输出参数：void*    返 回 值:  void**    作    者：Your_Name*    创建时间：2020-01-01*    其他说明：无*    修改信息：无*************************************************************************/

函数定义：

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

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

变量注释

1. 总述

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

2. 说明

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

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

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

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

拼写注释

1. 总述

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

2. 说明

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

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

TODO 注释

1. 总述

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

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

结语

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

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

— THE END —