谈谈注释

Posted 2020-10-21 hatlonely

大家肯定都有写过注释，注释这个东西不同于代码，与程序逻辑的正确性没有直接的关系，所以每个人可能都有自己的风格，每个人对哪里应该写注释，注释应该写成什么样子可能都有自己的理解。

我个人对注释的理解经历了四个阶段。

第一个阶段，完全不写注释，这个阶段还处在代码逻辑的实现上面，花大量的时间去调试，修改代码，根本就无暇顾及到注释这个事情。过了一段时间后，发现之前写的又臭又长的代码完全看不明白了，才意识到注释的重要性，于是开始慢慢进入了第二个阶段。

第二个阶段，哪哪都是注释，每个文件，每个类，每个函数，设置每个分支，每个变量，都有一个注释来说明，就怕漏掉某个小细节然后就看不懂了。后来又发现了一个叫做文档注释的东西（doxygen），这个东西不要太酷，可以根据你的写的注释直接生成文档，于是到处都是文档注释，每个文件里面都有一段简介，而简介里面最重要的内容可能就是 @author: hatlonely，生怕别人不知道这些这么low的代码是你写出来的???♀?，每个函数参数，函数参数的返回值等等，也都有详尽的注释，注释的长度已经远远超过了代码的长度。看起来好像妈妈再也不用担心我看不懂之前写的代码了，然而，一段时间当我重新读到add这个函数的注释的时候，我发现这些信息对我来说好像并没有用，这段代码已经足够的清晰简单，甚至比注释更容易读懂，那这个注释在这里存在的意义又是什么呢，仅仅是为了生成文档注释吗？而更大的问题可能是，如果我要新增一个函数，add3(int a, int b, int c) 我不得不按照之前的文档注释格式写一大堆的注释……注释的维护也是一个大问题，每次逻辑的变更，都需要去改对应的注释，如果忘记修改，注释和代码逻辑的不一致会让人更加困惑。于是注释的维护变成了一件非常无聊的事情，大大地降低了编程体验，而另一方面冗长繁复的注释也降低了代码的阅读体验。

1. // @file: 谈谈注释.md
2. // @date: 2018-01-19 14:00
3. // @author: hatlonely
4. // @brief: 一些对注释的理解
6. // @brief: 求两个数的和
7. // @param a 加数
8. // @param b 被加数
9. // @return 和
10. int add(int a, int b) {
11. return a + b;
12. }

第三个阶段，代码即注释。突然有一天，看到一个观点，代码是一种艺术，本身就是美，就像是诗歌，你见过一首诗歌里面插入了很多注释吗？注释不是对代码的翻译，而绝大多数时候，你在考虑用一个注释解释一个变量的时候，往往可以通过一个好的变量名来避免这个注释，同样，当你要注释某段逻辑的时候，也往往可以通过优化这段逻辑结构，使用一些可读性更强的变量来描述某些过程。于是我去掉了所有的注释，开始编写可读性更强的代码，开始纠结每一个普通的小变量的命名，开始站在普通人的角度去思考代码的逻辑，让代码更贴近自然语言，把让没有任何计算机基础的人都能读懂我的代码作为目标。于是现在代码看起来清爽了不少，代码本该如此简单。但是我满意了吗？并没有。

第四个阶段，必要的注释。毕竟代码不是诗歌，如果没有当时的文化背景以及别人的解读，大部分是诗歌普通人应该也是读不懂的吧。代码逻辑是由特定的场景决定，同一份代码在不同的场景下面也可能是完全不同的含义，所以为什么会是这样一个逻辑，是这个场景下特定的背景所决定的，而代码本身并不能包含这些背景信息。比如下面这段代码，关于ios过滤的这段逻辑，是因为目前的业务上暂时还没有这个需求决定的，这里的注释给了我们一些额外的信息，对我们理解这段逻辑有很大的帮助，如果没有这段注释，一个月后，你可能也忘记了为什么要有ios这样一个特殊的逻辑，不敢动也不知道，久而久之这些代码就成了谜一样的存在。嗯，看起来很优雅，现在我满意了！

1. func checkDeviceType(info DeviceInfo, deviceTypeSet map[int32]struct{}) bool {
2. // ios的设备类型不想android那么多，暂时还没有定向需求
3. if info.platform != "ios" {
4. return true
5. }
7. if _, ok := deviceTypeSet[info.deviceType]; ok {
8. return true
9. }
10. return false
11. }

下一个阶段是什么呢？是时候提高一下自己的表述能力了????。

转载请注明出处 
本文链接：http://hatlonely.github.io/2018/01/19/谈谈注释/