谈谈注释

Author Avatar
hatlonely 1月 19, 2018
  • 在其它设备中阅读本文章

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

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

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

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

// @file: 谈谈注释.md
// @date: 2018-01-19 14:00
// @author: hatlonely
// @brief: 一些对注释的理解

// @brief: 求两个数的和 
// @param a 加数
// @param b 被加数
// @return 和
int add(int a, int b) {
    return a + b;
}

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

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

func checkDeviceType(info DeviceInfo, deviceTypeSet map[int32]struct{}) bool {
    // ios的设备类型不想android那么多,暂时还没有定向需求
    if info.platform != "ios" {
        return true
    }

    if _, ok := deviceTypeSet[info.deviceType]; ok {
        return true
    }
    return false
}

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

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