给代码写注释时有哪些讲究？

客官°小女子只卖身不卖艺 2022-10-10 06:12 150阅读 0赞

![0D5F937FE12312312D81F17F.jpg][]

程序员的成长之路

互联网/程序员/技术/资料共享

[关注][Link 1]

阅读本文大概需要 4.3 分钟。

来自：strongerHuang

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

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

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

**注释风格**

**1. 总述**

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

**2. 说明**

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

**文件注释**

**1. 总述**

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

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

**2. 说明**

法律公告和作者信息：

每个文件都应该包含许可证引用。也要为项目选择合适的许可证版本(比如,[**Apache 2.0, BSD, LGPL, GPL**][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` 时, 一般都是写上自己的名字。

**结 语**

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

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

<END>

**推荐阅读：**

[横空出世，比Visio快10倍的画图工具来了。][Visio_10]

[糟糕程序员的编程风格。。。][Link 2]

最近面试BAT，整理一份面试资料《Java面试BATJ通关手册》，覆盖了Java核心技术、JVM、Java并发、SSM、微服务、数据库、数据结构等等。

**获取方式：点个「****在看****」，点击上方小卡片，进入公众号后回复「****面试题****」领取，更多内容陆续奉上。**

朕已阅 ![1a013ea29f29718f6a7846e4222bfb85.gif][]

[0D5F937FE12312312D81F17F.jpg]: /images/20221005/30af5e887c79481994d8bffece91f0f6.png
[Link 1]: https://mp.weixin.qq.com/s?__biz=MzUyNDkzNzczNQ%3D%3D&chksm=fa24f0bacd5379ac93d74ffebac826d2401fd494f82e900e5102a8bf968f108e4ec72a4ad548&idx=3&lang=zh_CN&mid=2247487442&scene=21&sn=61e758d4bf9f15a3419fd028146469a3&token=1854383306#wechat_redirect
[8c44c960a3ac654378ed68a885a1e742.png]: /images/20221005/104e941ea86b41ef9f9286ecbef237cb.png
[Apache 2.0_ BSD_ LGPL_ GPL]: http://mp.weixin.qq.com/s?__biz=MzI4MDI4MDE5Ng%3D%3D&chksm=ebbbb605dccc3f138bfa917e47ae3d347254ff88c2d42ccdb6b7493fcdb38f579b88c657939d&idx=1&mid=2247490542&scene=21&sn=489b574b83cb8a3a5e80b26e8037f8f2#wechat_redirect
[Visio_10]: http://mp.weixin.qq.com/s?__biz=MzUyNDkzNzczNQ%3D%3D&chksm=fa275d90cd50d48665e98979a7e1f098392264c939a69fd43e4bf49dd1d41e9fb149f545cca7&idx=1&mid=2247508728&scene=21&sn=c73176e31fe3d1941ebfb02f651e7332#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=MzUyNDkzNzczNQ%3D%3D&chksm=fa275d8ecd50d49831b79537fcfa7f48b21b6b0b25520f6f94cf8a569146ed1cb70ab2a65f33&idx=1&mid=2247508710&scene=21&sn=1ee21c19a3e0698ac01dfb88662b9fe3#wechat_redirect
[1a013ea29f29718f6a7846e4222bfb85.gif]: /images/20221005/59d5642cf7ca4b658d7ea84303c85b68.png