无痛苦的软件维护——文档和代码

程序维护的时候经常遇到两个困难：

1、不知道这段代码是实现什么功能的（code —— function）；
2、不知道这个功能是实现什么需求的（function —— business）。

解决第一个问题是比较容易的，大家都是搞技术的，一头扎进代码里去，看上几十分钟，通常就能明白：原来这段代码是从数据库里面找到前三个月一直处于停机状态的号码，然后把这些号码放到一个叫做QUIT_USER的数据表里面去。

第二个问题就难了，经常从代码中是看不出来的，于是项目开发的过程中就制造出来了大量的文档，来帮助开发者交流这个问题，也让将来维护这段代码的人知道这个知识。

我们可以查找与这段代码相关的文档，文档上说：这段代码把停机三个月的号码放到一个叫做QUIT_USER的表里面，一个月以后，这些号码由另外一段代码拿去筛一下，把最近刚交了费用的号码删掉，剩下的用户做退网，号码回收，冻结半年以后可以重新使用。

令人难过的是，维护程序的人很难有幸看到如此贴心的文档。他们查了半天经常看到的是：这段代码按照xxx的规则，从xxx表中查询数据，然后再把结果的数据经过xxx的处理，放到QUIT_USER表里面，over。你仍然不知道他到底是在做什么。

并且，文档与代码的同步也是一个难题。不仅是文档，即使是代码中的注释，谁又能保证他真实的描述了系统的运行方式呢？时间紧张、错误的理解都可能造成文档与实际情况不同。我们假定写文档和写注释的人是认真的、不犯错误的，他们也必须忽略一些细节，他们不能什么都写上去。而他们忽略的细节很有可能为以后的维护带来麻烦。

很多项目都有这个问题：business和function是脱节的。熟悉客户业务的人设计出一系列的功能点，这些功能点按照最初的设计是可以完成客户的业务的。然后这些功能点就拿到开发人员那里去造出来。而开发人员对用户的business其实是不了解的，他们的眼中只有function。到了维护的时候，business发生了变化，function重新设计。经常是经过一番修改，程序按照开发人员的思路运行良好，但是用户却一个劲的摇头：“不不，不是这样的，我们要的是这个……”程序到底解决了哪些business，已经成了一个迷。

什么东西可以最准确的描述程序的运行过程呢？只有代码本身。并且，经过精心设计的代码也能很好的对business进行描述。比如刚才说的那件事情，一段代码把号码放到QUIT_USER里面，另一段代码从这里面筛除一些号码做退网。这两个function其实在business方面都属于一个点，那么就应该让这两段代码写在一起，封装起来——这就是高内聚。并且这一段代码内部的操作应该与其他的功能没有任何关系，除非那个功能与这两个功能具有business上的共同点，别的代码应该不知道QUIT_USER是个什么东西——这就是低耦合。

一个项目的代码，总是由大尺度的构思开始的，然后越来越贴近细节，牵涉越来越多的技术。但是写到最后，代码应该回到对business本身的描述。代码越贴近business，对维护的帮助就越大。

我现在要维护一个公司的财务管理程序，我想知道职员的工资里面是不是已经计入了他们的个人所得税。我找到Account（会计），他应该有一个方法，每个月运行一次，把Salery发给Emplyee，我找到这个Salery，看到里面已经包含了Tax。我发现Account计算这个Tax的时候使用了一个Stratagy（策略）。他调用的是一个名叫Stratagy1998的策略，以800元作为基数计算个人所得税。现在这个基数已经发生了变化，于是我修改这个Stratagy1998、或者替换掉一个新的Stratagy2005。这样就完成了一次变更。并且我知道这样修改不可能影响到business不相关的东西。

文档永远只能表示“某时某刻我们曾经这样想过”，让文档时刻保持与代码的同步是不实际的。要想知道“现在程序是怎样运行的”，只有代码能够告诉我们。文档应该配合代码，做代码不能做的事情，配合把business说清楚。而不应该与代码发生冲突。

文档应该去描述代码无法说清楚的事情上，比如用户的工作场景、某个需求是由谁提出来的、大尺度的程序设计、重要对象的运行时序、系统安装手册。比如下面这个图，他清楚的说明了“销户”这个行为在整体的需求中处于什么地位。这样的东西用代码说清楚是比较费力的。当然用代码也能说清楚，比如可以使用State - Action模式，但是总归不如一张图表示的这么清楚。



XP和Agile方法所提倡的“尽量少写文档”，就是基于这样一种设计理念：尽量的用代码和测试代码来描述business，以达到知识的交流和维护的便利。代码是最重要的沟通语言。在代码说不清楚的情况下，文档也是必须的。

评论

1 楼 bloodwolf_china 2012-05-21  

是的，深有同感。