注释及文档的故事

出处：http://blog.krzycube.net/interface_func_comments/

---

昨晚从会议室出来，发现有几位在金山时的同事(@HanTuo , @lidaobing , @hangzhupeng , @wangdong)在twitter上讨论关于接口注释的问题，整理如下,相应回复的紧贴一起，就省去了twitter中多级RT吧:

HanTuo: 实在不喜欢代码里面有太多注释。函数注释太多说明实现的太复杂，接口注释太多说明接口太复杂。
HanTuo: 其实我说的也没道理。个人习惯吧。反正我就是不喜欢。看着特别难受。

lidaobing: 我觉得接口注释是非常必要的, 用来定义你这个接口的行为, 比如抛异常还是返回null, 这种很难猜中的。函数注释我同意你的观点。
HanTuo: 接口注释我比较喜欢搞一个API文档。唉，个人习惯吧。我看到代码里有一大段绿色的就浑身难受，有生理反应，一点不夸张。
lidaobing: 调一下配色吧, 比如 xp 蓝?

wangdong: 没错，能用代码说清楚的事儿非要连篇累牍整注释，痛苦的很
hanzhupeng: 在编辑器里面屏蔽掉注释就好了

看到以上内容，我想大多数程序猿都心有戚戚焉，近来正好在这上面有个的经历不妨一说。先来理理上面提到的需求：

1. 核心：代码里不能有太多注释

2. 接口还是需要注释的，例如API文档

3. 函数头顶上飘太多绿色不行，这颜色会触发心理及生理反应

4. 尽量用代码来说清楚设计意图，实在不行编辑器里屏蔽注释

然后开始讲故事了，小朋友们请坐好，陪同的家长在这方面有深刻认识的，可以去外面抽根烟消磨时间，不用在这里掺和了。
4月初入职的时候，要加入的项目已经有了一版设计稿。看懂了之后不得不说，那是个很棒的设计，你要知道那作者可是头大牛。不过，对我这个没有参加最初设计的人来说，这个这个……为了不让某人说我有夸张的嫌疑以及被鄙视阅读能力，就不罗嗦：

那一上来20多页的设计文档--满篇的文字

概念化的描述--实际系统中却是遍布网络的消息

代码还没开始写呢--接口描述也就先放里边吧

基本读了后面忘了前面，理解能力备受打击--深入理解一下脑袋就有打结倾向

等等这些问题了。我想说的是，其实我一直不知道除了设计者之外，有几个人真的静下心来深入理解了这些设计稿了呢。说“这些”是因为不止是咱这项目吧，估计有项目的地方就有这故事，这玩意儿是在不怎么好读。因为它真不是什么好写的东西，就跟代码里头的注释一样，写粗了不行，写详细了更郁闷。要么就跟高爷爷说的那样，咱上Literate Programming，写程序跟写小说似的，还用专业的Latex加自创字体排版。读者贼快乐，从头顶爽到脚底。放心，这些工具几十年前就bugfree了，不会有印刷错误，绝对不带勘误表，那什么改了代码忘了更新注释的事情，明显不会存在的嘛。另外我们的情况更特别，其实这Team至今也还是只有两个人，于是那个写第一稿设计的人就不言而喻了，有兴趣参加设计稿阅读比赛的同学赶紧报名，前32位报名费优惠。

接着俺们就准备开工了。在实现这个设计稿中描述的系统之前，觉得有必要先由一个底层的库来搞定消息传递的问题，这东西基本顺利搞定，称之为CERL，是模仿实现Erlang Style Cocurrency。可直接在这个库之上就来写一堆的消息处理，在C++ 这种某某标准一拖再拖继而不知道拖到猴年马月的质朴语言里搞序列化，又实在是会挠光头发的事情；要知道这些未进化完成的程序猿每天受的辐射量巨大，发根可不怎么稳固。于是就想着，要不搞个xx语言，来描述一下服务进程，然后让xx工具来生成底层代码？一合计，这玩意儿不错啊，于是先定义了一个描述语言，贼简洁，什么返回值啊，异常描述啊，基本一行搞定。然后搜罗出一堆语言啊，库啊，工具啊就开始准备给这个刚怀上的孩子造儿童专用自行车–编译器了。就跟吃火锅那么简单，反正见到什么菜啊肉啊，花椒啊大蒜啊就往里面加点。什么C++库当底裤，PHP处理做缎子，JSON表达当化妆，Erlang风格作亮相……，能用的全给它用上，什么流行、够酷就用什么。大牛同学随随便便翻翻以前的代码，找了个文本处理库，三下五除二写了个暂时只会：

  “报告，失败了”
  “败在哪了？”
  “忘了！”

的前端分析器。接着俺又临时学了学PHP，处理了JSON就捣鼓出来一个Code Generator，这个东西会报点错。于是号称Service Descriptor Language的山寨语言出品了，写个描述文档，没几行，通常文件大小不超过2k，装到那儿童车编译器里这么一跑，直接从Erlang样式的接口描述，生成服务器进程的底层代码，什么同步/异步调用，消息封包/解包之类的脏活累活，能干的全替你干了，你只要往空白的函数实现体里填几行代码，这孩子立马从小班升大班，眼看就能上小学。Erlang里头管这玩意儿叫啥来着，噢，gen_server。

不好意思，刚才走岔道上去了，咱接着说着设计实现。搞完了底层库，俺这边又弄完了山寨语言。那边立马就出了一个简单DEMO了，要不怎么说瞬间升级到Beta版呢。可我一看傻眼了啊，仨东西：一个设计稿；一个SDL文件，不带注释的，倍儿纯洁；几个代码文件，同样纯洁得跟小白花一样。因为大家都觉得这代码要是满篇注释吧，那真不是人看的，要是需要在代码里连载注释当小说看的，那更不是好代码。要不说设计是设计，实现是实现，一上来愣没理解顺溜了，不知道这消息哪跟哪。耗了不少力气对应上了，脑袋里走了走流程，接着往下写功能呗。写着写着不行了，再牛的设计，总会有点缺陷，那就改改吧。这下痛苦来了，一个结构缠绕的设计稿，人家费好大心思才弄得看起来不那么累了，那是能随便动的啊。这一改设计，引入几个新概念，立马就多掉几根头发。此处说个不该出现在这种讲故事场合的“语重心长”: “千万别轻易决定在系统里引入一个新概念，会被同胞们寄明信片悼念的!”

眼看着键盘缝里的头发比饼干屑还多了那么一点点的时候，悟了，这不咱造了个山寨版SDL么，那不是一般的山寨啊，乍一看名字就是直接盗版“卖哭了软水果公司”（注1）那iDL的，跟M8啦，HiPhone啦，那还是可以拼一下的。
写都市剧本，弄张纸简单一概括，那叫一个抽象，就画几个框，列一下都有哪些角色，然后用点虚虚实实的线条表示跟这几个MM之间的暧昧关系。再弄几个附录把各种琼瑶式对话一列都市情感纠葛的剧本大纲就算出来了。

故事初期，啥都抽象朦胧的时候挺美好，不闹心。可这摸摸小手的初级阶段一直下去，再持续就一百年过去了。就要仔细考察各个人物，挑一个准备来点实质性转变了。这下这彪悍抄袭外国设计大陆厂商制造的SDL文件就派上用场了，用来描述下她们是如何迎来送往，以及这些角色MM们每季度什么时候要向Master交税（发送某些状态消息）之类的，那是最适合不过。

module tv;

code invalidaccount = 0x11;
code accountexception = 0x12;
code unregistered = 0x13;
code cut = 0xff;

type BillNumber = UInt32;
type ExceptionMessage = String;
type BillArray = UInt32[];
type Locale = String;
type PayStatus = ok|unregistered|{false,ExceptionMessage notenough};

server RoleBoyA
{

RoleBoyA(Locale lc);
//
// From: Director
// Brief: ' xxxx '
// Arguments: "none" - 'xxx'
// Exception: "cut" - ' xxxx '
// Remark: ' xxxx'
// Note: ' xxx '
//
[id=1] are_you_ready() -> ok | false;
[id=2] actionTalk(String msg) -> ok | {cut, ExceptionMessage};
[id=0x81, async] recvTalk(FirstArray something);

}
server RoleGirlA
{

……
[id=0x81,async] payDuty(BillArray bills);
[id=ox82,async] payResult(PayStatus status);

}

选好了之后就要跟对方亲戚朋友来来回回扯皮了。家庭关系，那是讲究辈份的的。重要问题，你不能先找人家小表妹谈，更不能找人家表姐刚出生的孩子谈，这得有个流程。画个流程图把这先先后后的关系理顺，这关就算过了，这后边的事情，多少彩礼、摆多少桌（这不就是空间使用吗）那都是不含糊的，一路顺畅无比。
要说这画流程，不比那传统大红双喜剪纸艺术简单。用Visio这等超级牛力工具，不是像我这样刚放牛还没爬上牛背的牧童能轻易搞定的，老牛则更是嫌这草太老，口味不佳。于是翻山越岭，跋山涉水，到那遥远的西天求得一部梵语经文，手拈兰花，念完梵文，这流程图它就出来了。不信？那就看看咱的修行成果：
从这个：

Director -> RoleBoyA: are you ready?
activate RoleBoyA

RoleBoyA -> RoleBoyA: prepare something.
RoleBoyA -> Director: ok
deactivate RoleBoyA

RoleGirlA -> RoleBoyA: Hello, xxx

activate RoleBoyA
RoleBoyA -> RoleGirlA: Hi,xxxx
Director -> RoleBoyA: cut,xxxx
deactivate RoleBoyA

变成这个：

也想画图？ 访问这个：http://www.websequencediagrams.com/

要不今天咱就到这？
“等等，不是听说西天是金光万丈，五彩孔雀漫天飞的吗？你这些东东怎么净是黑白两色这么凄惨？”
哟，不说还给忘了，说道这个颜色问题，在SDL这山寨产品诞生的时候，就考虑过怎么推广。也得给它整两广告啊，就想着给它写个啥emacs-mode啥的，差不多就是天朝台黄金时间的广告级别了。可现在看街边免费赠送八卦小报的比看新闻播报的多。不过咱不能啥报纸都上，那得选专业的！重要的是免费，比如那什么上海地铁里发的那一时代报知道不，那发行量，那是相当的大。上班随手取一份，方便；还能读到夹页广告。
申请一笔经费出去一考察研究，发现这Notepad++不错，发行量大，方便好用，随便装插件，跟往里边夹一广告那么简单，关键还免费。
可这人家也没有现成的SDL高亮规则，自己整一个还挺累，看有没有现成近似的盗版一个算了，咱的口号是：“山寨货，不求更真，但求更假”。

试了半天，Notepad++崩溃了N次，看来这规则解析还有些漏洞，最终选定了Smalltalk，几个好处：
1. 首字母大写为类型，高亮之
2. 首字母小写为atom， 不高亮
3. 字符串后紧缀一冒号，立马变色
4. 双引号跟单引号那颜色还不重复。
SDL一看到这SmType的“色x小说”语法规则，那真是干柴烈火，谈好价钱（注释规则）就立马勾搭上了。从此山寨喽罗和贵族美妇生活在五彩斑斓的世界里了：

故事讲完，回头看需求：
1. 代码真没注释嘿
2. 真有API文档嘿
3. 配上流程图一看就明白
4. 生活五彩斑斓，但绿色不多