那些害人的编码“神谕”

原文链接：http://blog.solrex.org/articles/words-that-make-code-bad.html

同其它领域一样，计算机科学和工程领域也是群星璀璨，有些耀眼的星光甚至刺得我们无法直视，只能匍匐在地上聆听神谕。也正如其它领域一样，虽然大家听到的是同样的话，却有各式各样不同的理解。我这里想讲的，就是我观察到的不同理解引发的现象。

“过早优化是万恶之源。” 这是 Donald Knuth 的一句名言。虽然大部分人都不知道，或者会忘掉前面半句：“We should forget about small efficiencies, say about 97% of the time:premature optimization is the root of all evil.” Knuth 说出这句话时，可能想不到这句话会多么地流行，多么根植在很多人心中，以至于成为程序员偷懒的借口，阻碍进步的动力。因为有了这句话，在你指出别人代码中可以优化的问题时，还必须浪费口舌来解释这样的优化是必要的，不是过早优化或者过度优化。

就我的观察而言，对很多程序员来说，其能力还远远达不到过早优化的地步。但他感觉自己受到了 Knuth 的神启，仿佛具有了某种魔力，不优化代码反而成了一种优越感！关于大多数人是否具备过早优化代码的能力，我可以举几个至今我还觉得神奇的例子。

我供职的公司内部有这样一个模块，隔一两个星期总会挂掉几台服务器，现象是内存占满导致服务器假死或者宕机，但事实上根据请求推算根本不会同时使用那么多内存。最后的排查结果发现，每个线程都有这样一个数据结构，它的内存是只增不减的。当你调用它的 clear 接口，它只会把所有的内存还回自己的内存池里，而不是还给系统。这就导致可供分配的内存越来越少、越来越少...

还是这个模块里，仅仅加载一个几 K 的配置文件，就能够占用超过 1G 的内存。为什么呢？因为它用 char str[MAX_CONF_LEN] 保存配置字符串，用 struct xx_t xx[MAX_XX_NUM] 读取配置，而且这个 struct 中还有嵌套的 struct yy_t y[MAX_YY_NUM] 数组。

该模块是个个例吗？还是这家公司，一个全公司使用的公共日志库，LOGGING 宏定义中直接传一个需要系统调用的函数作为参数，导致无论关不关该级别日志都要进行一次系统调用。

这家公司好歹也位列国内顶尖的互联网公司之一，工程师的招聘要求也是极其高的，还会普遍出现这种肆意浪费资源的情况。那么我想对于大部分工程师来说，谈避免“过早优化”、“过度优化”，还为时尚早。

还有一句名言“好代码本身就是最好的文档。当你需要添加一个注释时，你应该考虑如何修改代码才能不需要注释。” 这是 Steve McConnell 说的。同样，大部分人都不知道，或者忘掉后面半句：Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer. 如果你是程序员，回想一下多少次跟别人讨论代码是不是必须要注释时，这句话被引用到；有很多次在写代码时喜爱这句话，又多少次改别人的代码时痛恨这句话。

还是从我个人的观察来看，对很多程序员来说，其编码能力还不足以达到“代码本身就是最好的文档”的地步，包括我自己。敝司招聘过很多顶尖的工程师，有传说中的各种杰出前辈，可能在各种学校、公司内部事迹广为流传。但若是你哪天继承了他的代码遗产，就会发现很多传说中的明星跌落凡尘。成百上千行没有注释，使用一个公共库函数时要么接口就根本没注释只能基本靠猜，要么即使注释也语焉不详让你踩到未注明的大坑。每到这个时候你心里总会暗暗骂娘，后面别人再谈到他的光辉事迹时，你跟随讪笑时心中暗自腹诽：“牛逼个锤子！”

但我想很多人争论的焦点是：“注释是不是不可省略的、要强制执行的？”即使个别人能力真能达到“代码本身就是最好的文档”的地步（我还没见过），我也不建议在团队中传播“注释可以省略”这一想法。因为如果你说“注释可以省略”，可能你会发现大家都理解和实践成“终于可以不写注释了”。如果一个刚刚大学毕业、脑袋里从来没有过 documentation 概念、从来没写过注释的新人进入公司，就“终于可以不写注释了”，那么我想他的代码会很难达到“代码本身就是最好的文档”这个级别。因为他根本没有机会懂得什么叫做 documentation。

在公司里，代码注释深远地影响着团队合作的每个人，以及软件生存期里所有的维护者，甚至会影响自己的职业声誉。所以无论别人怎么想，我对注释这个问题的答案始终是：“注释是不可省略的，越完善越好的，甚至强制执行矫枉过正也没关系的！”