怪怪谈注释

闲话不说，本篇主要讨论注释的非必要性。

以我个人的经历来说：从满篇清晰工整的注释到一字未写的（过于玩具的不提，只谈那些逻辑复杂或者职责分配分散的），上至大牛神作下至身边比Community Server写的还乱的，我从没看过注释。

另一方面，说实话，虽然很多人B4我这样的，但是我仍然要恬不知耻地说，我也基本不写注释；而过去在作为一个管理者的角色时，我从来不要求别人写注释。什么叫做“基本”呢？

就是说以下两种情况例外：

1. 一句或一段代码抽象过了头，也许需要跟业务相关的描述建立一个直观的对应。

2. 因为安排的不够妥帖或者很难妥帖，一段逻辑中蹦出一句为不相关逻辑服务的代码。

而这两种情况出现的极少。

当然这和我经历过的几个工作环境有关系：无论是遗留还是全新，我总能自己决定是不是重构或让别人重构；如果我花费了比预期更多的时间读代码的话，我也总能让人相信那就是必要的。

但是可以想象，一个比我接触过的环境更加赶鸭子上架的环境，如果没有把设计和代码整理好的时间，也必然没有做注释的时间。很多人否认这一点，认为加几句话自己以后看也清楚，费什么功夫。

不是这样。

在头脑发热的时候，大多数人只想抓住自己当时稍纵即逝的灵感（无论在哪个水平上），他脑子里怎么想的在当时是非常明白的，而5分钟后就未必了。这时他确实应该整理思路，可List上却有其它更重要的事情。【1】

那么我的观点是什么呢？

要么组织上并不存在资源（时间、人力）不足的情况，这时大多数设计和实现因为足够好而无需注释；要么就根本没时间写注释。这绝对不是作者的错，有时甚至不是组织的；尤其从作者的角度来看，根本没辙。【2】

唯一的办法就是不断增加阅读代码的水平、理解业务逻辑的水平。这两个能力获取的信息相互印证，一点一点往前走。组织没提供给你足够时间怎么办？那不是你的错，也不必为此有愧疚或愤怒，咱也是没辙。

那么什么时候也不需要注释和文档吗？不是，比如库作者必须写明接口如何使用就是一例。但在这个之前，首要的一点是，尽量不要设计的让人深入库源码才能得心应手；需要说明的是，库是如此，而框架却很难做到这样。

也正是库和框架的区别，导致GoF中其中一个在若干年后放弃了框架式的设计。但是大家都有反射ASP.NET源码的经历：至少从我个人来说，即使对它的设计颇有意见，但也从来没有产生“要是有注释就好了”的念头。

合格的程序才是我们想要的，而不是注释。不合格的程序往往也就意味着连写注释的条件都没有：即使不是因为当时的具体情况，而仅仅是因为组织雇佣了一个水平低下且不负责任的人，这也是一个资源问题。

大家知道我很少说人情世故，上面这些话也不是从这个角度分析。

不过有一点，没有什么是我们能要求别人的。我们是擦屁股的人的时候，我们要知道社会认可了那个留下便便的；我们是管理者的时候，我们应该想办法为组织争取更多的资源，这是管理者的一个职责和义务所在。

是不是所有情况下都如此恶劣？当然不是。

比如就一些公司所针对的业务来说，可以以很低的成本就形成越来越多的约定和约束，让程序员可以自由发挥的余地越来越小。但这个过程主要是自上而下的，而本篇的目的是给任何水平层面上“不写注释”的程序员说两句，就不多关注了。

没办法的时候呢？ 只能听天由命了。

 

---

 

P.S. 很多大牛甚至喊出了“注释是有害的”这样的口号；如此看来，我还是不够激进了，惭愧。

注释一：

什么叫更重要的事情？就是说，已经完成的代码做的再完美、文档在齐全，下面这件事不做或做不完，整个项目也会死。

一次完善也许可以说不算什么，但是谁写程序能够只有一处需要完善呢？我们要明白的是，当我们为几处生气的时候，这仅仅意味着我们只见到了这几处。

这样的代码即使不能说值得表扬，但针对具体情况，也许已经不错了：此人当时在其他更必要的地方花费的心血是我们没能体会的。

如果处处都让人生气，这就一定是一个非常严重的资源问题，不属于程序员这个层次，不再赘言。

注释二：

有人可能会说了，你别操蛋了，哦，至少够我写注释的时间，就不够那孙子了？三点：

1. 你面临的情况不同。人无法两次进入同一条河流，这点没法真正彻底的反驳。

2. 你水平比较高，也不过是因为组织掌握资源的状态和能力发生了变化；没人应该因为水平低挨骂。

3. 重申一遍个人观点，如果一个人真有足够的时间写清晰的、很难让任何人误解的注释，他应该把这个时间花在代码上。

多说一句的是，我并不是在说存在即是reasonable，具体问题具体分析。