注释二三事

如果一年前你问我，你写博客吗？
——神马？博客？那老掉牙的东西，已经是旧时代的产物了。

是的，博客，微博，论坛，甚至贴吧，都已经被我扫到了一个土簸箕里，扔到脑后了。

现在开始写博客，很大的一部分原因是是想恢复我那可怜的写作能力。

许多程序员都曾读过《程序员的呐喊》一书，想必对其中意见鲜明，立场坚定的JAVA黑（SteveYegge）有很深刻的印象。

不知道你们还记不记得，他有保守派和自由派的理论。

注释和保守自由有关系？

是的，因为在渣渣层级（1-2年编程经验，不排除大牛也有这样的争论）中，有这样一个问题。

程序要不要写注释？

我将严格撰写程序注释，视为保守。

有人会说：“不不不，史蒂夫的保守与自由不是说这个的。”

我回答：“难道注释不是一个战略级别的事情么？”

史蒂夫的保守与自由，阐述的是一个系统不同的架构，编写方式。

是否需要注释，是一个非常重要，但被忽略（起码是新手，不会注意到）的事情。

如果你关心这个问题，你在网上应该会搜索到很多这样的争论，也有无数痛心的例子（或许你遇到过）。

比如：在一个阳光明媚的日子，开开心心的到新公司，与新同事打招呼，打开自己的电脑，开启sublime|VI|各类IDE，连上SVN|Git，检出项目，打开，关闭，找到你的直属上司，提出一个蛋疼的问题：“我能重写这个么？”。

为什么？因为这个庞大的代码库没有一行注释，而你的任务，也许是重构项目，或者代码大版本迭代，你发现不得不痛苦花大量时间研读代码。即便是在原有基础上修改逻辑或对接功能，也是好似千刀万剐一样的事情。

我想你会另起重写，我说的对么？

写不写注释的问题似乎尘埃落定，无论是为了自己好，还是为了自己东家好，还是为了自己的继任者也好，写注释都是胜造七级浮屠的事情。

无意义的注释

较为主流的观点，是这样的，尽量避免无意义的注释，写必要的注释。

什么是无意义的注释？——比如这个：

一般不写注释的人，都有两大观点。
1.注释拖慢程序编写，甚至运行速度（速度控的极端表现）
2.这破代码用写注释？

上面无意义的注释就是属于后者，而后者驳斥不能。

没人希望自己是傻子，或者被人看成傻子，而且这样的注释的确太傻，所以，大家一致点头认为，这样的注释，应该一丝不留的消失在代码群中。

随着编程经验的增长，大量没有注释的代码应运而生，因为，没人比你更了解这个程序有多么简单，写下一行注释都是可笑的行为。

然后，一位菜鸟程序员来到你的代码面前，默默地关上了屏幕，惊叹于大神的思想，并决定重构你的代码。

是的，这就是我要说的，所有人都一致认为，这样的渣渣注释不应该出现，但却低估了这样做所带来的后果。

有很多大神（或者高级码砖工）可以一目十行，精确定位BUG，3天读懂项目逻辑，不在此讨论之列。

我没有说，大家应该多写这种如白开水一样的注释，但成熟干练的你有没有想过，一个不懂业务逻辑的人，看到你的代码是否会头疼，仅仅是因为在该注释的地方，少了那几行小字。

在写代码的时候，多想想这陀玩意，拿给另一个人看的时候，他能否快速读懂，再决定是否写上注释，我想这才是合适的做法。

我的注释

过度的，难维护的注释见过没？——啥？注释还维护？

如果你还没见过需要维护的注释，那么由我这个陷入注释狂病症的人，给你说说什么是注释到死。

大体上，我有三种严格的注释

1.可删除注释

这就是上文提到的，白开水一样的注释。可能你也注意到了，用中文写注释这种比较“不新潮”的写法，多半是又碰到一个英文不精的程序猴。

一个没有长久编程经验的年轻猴子，又是个英文苦手，如何快速读懂自己N长时间的代码？——我选择注释。

可以看得到，右边注释在本行的，就是我所谓的可删除注释，（比较重要的逻辑注释都是注释在注释行的上方）。

在发布到线上之前，我都会把这些丢人的注释删除掉，但不要忽略这样的注释对读码的效果，特别是对于初级入门者来说。

2.doc注释

这个很好理解，如果你是用比较重型的IDE，比如ZendStudio或PhpStorm，当鼠标悬浮上去之后，显示出你指向的方法的参数注释，爽就一个字！

这是我极力主张并绝不摒弃注释，他能提醒你写的成员方法到底是干什么的，而不用去通过函数名或读代码来猜测。

他也能帮助另一位程序员定位错误的时候，知道这陀烂码是那个混蛋写的，并得知他的邮箱（@author）

3.改动注释

出于对其他程序员的尊重，和谨慎。在改动其他人的代码的时候（甚至是没有author的野孩子）我都会写下下面这种，“变态”的注释

我的灵感来自于这个：

是的！我已经看到你一副扶额的表情了！（其实已经简化两个版本了）

这就是我所说的，需要维护的注释。不过在诟病自己之前，我想先说说这个修改编号是什么。

模块名称+程序功能+修改体系编号，前两个无非就是标定修改所处的位置，后一个是重中之重。

因为你的一次修改可能牵扯到多个不同的地方，比如我需要修改这里，也要修改那里（今天老板让我增加活动类型，明天让我修改活动参加方式）。

而且，你有可能回滚。（还是觉得3天前的功能比较好的老板，兴冲冲来找你，而你只能通过svn去找历史版本）

我们来举个栗子
老板今天告诉你：我们不需要那么严格的判断了，判断模块里去掉一些必填项吧。
于是你新建了一个：activity_check_01，并修改了从模版到Action共5个地方（所以多了5个activity_check_01）

第二天，老板觉得用户不写自己的资料，我们的站怎么能精确定位用户呢？

于是回滚，你要做的，就是查找所有activity_check_01，原样恢复，方便吧！

是的。我当时就是这么想的，并解决了多次业务滚来滚去的问题，直到我发现，这样做巨大的麻烦。

1.程序中到处都是大片注释。
2.遇到大批量程序重构的时候，你不知道该不该留下这几百行代码。
3.修改的地方太多，体系编码（后面的数字）我忘了到第几个了
4.该死的！今天加班，我想赶紧完成，回家！

最可怕的是，有人再次修改，而他没有你这个习惯，或者你再次修改却懒得写注释（这种情况其实更多）。

这会导致，代码和注释，文不对题。

OMG，我是该信代码还是信注释？

你需要时间，来维护你的注释，就像维护你的代码一样，我想发现这种问题之后，不在少数的人选择丢弃注释，然后，一边骂娘说别人不写注释，而他自己也不会写。

所以第三种注释我开始选择性的编写，不再作为一种执念（其实更多的是依赖SVN的历史版本比对…）。

总结

诚然，注释这种东西，就和文档一样，拖慢了开发的脚步，但这两样东西带来的受益是难以想象的，镌写过度的注释也是需要量力而行的。

如果你是一行注释不写，或者注释与代码1:200以上，无论作为晚辈还是前辈（有可能是很久以后你看到我写的东西），请写下你的注释，让同是苦逼的下一任（有可能是年轻的应届）少拙计。

如果你和我一样，有过度注释的习惯，不妨放下屠刀立地成佛，留下doc和寥寥数笔核心逻辑注释，受人尊敬，不觉得是很舒爽的事情吗？

此文未经排版，有感而发，文体混乱，意见偏执，欢迎讨论，想提出激烈的不同意见的人，你可以来打我，或者找我喝两杯，谈谈明天中午吃点啥。