软件开发文档的持续集成

大多数程序员，都极度痛恨写文档。Coding是愉快的，而Write是痛苦的。有一部分原因，其实是要归咎于程序员自身，以我的经验，很多程序员往往会“艰于表达”，尤其是用“文字、图表、PPT、Word”之类的Office Document来表达。当然，还有一部分原因，是由于很多项目开发实践中，文档的前后矛盾、形式主义、反复修改、歧义重重，常常让程序员们抓狂。

UML是一个比较好的工具，但是，仅仅靠UML，是无法将项目的知识描述清楚的。也有不少项目组在引入了UML之后发现，文档的工作量不但没有减少，而是更多了。随着项目的进展，需要维护的设计文档数量，也更多了。也因此造成了更多的前后矛盾，形式主义，反复修改。

根本的痛苦，并不在于一开始写一份文档，而在于所有写下的文档，都必须跟随项目的进展而随之变化。当我们写出来的文档越多，需要被持续维护的文档也就越多，需要反复检查文档间的可能存在的矛盾也就越多，所有扔出去的石头，最后都会落回到自己头上。

于是，还有不少项目组，将文档工作与代码工作截然分开，文档就写一次，用来应付上面的管理层，而代码自管自的继续开发。对于小型项目来说，这其实是一个不错的权宜之计。但是一旦项目越来越庞大、复杂。所有的隐性的知识，都仅仅存在于程序员的脑子里，所有成文的东西，都可能是错的，而真实的情况，却隐藏在代码之中。如果代码质量再糟糕一些，后来维护的朋友，就遭遇火坑了。

文档，写还是不写，这是一个问题！

还记得测试驱动开发吗？为自己的每一个方法，每一个类，都写出单元测试来。不但如此，更加彻底的做法是，在写代码之前，先写测试用例。这样才能保证不会忘记写测试用例。更大的好处在于，这样有助于思考、有助于获得更加完善的设计，有助于写出更加高质量的代码，有助于安全的重构，有助于自动化的持续集成实践。总之，是好得不能再好的一项开发实践。

这一实践之所以可行，就在于他将繁杂的集中的测试工作，分解为日常的，必须不断进行的工作。当你每天都在写测试用例，当你的每一个测试用例，都能够与代码完全对应时，压力反而减轻了，工作量也更少了，更重要的，一些优良的习惯也因此被养成了。

在两年前，我要开始一个全新的P2P网络电视项目时，也在考虑关于文档的问题。当时我发现了Open Source的WikiPedia。这是一个PHP的WIKI，最大的应用是维基百科全书。因此，这个项目的质量就绝对值得信赖。我就将它拿过来，作为我们项目文档管理的工具。

用Wiki来管理项目文档，基于以下一些考虑：

• 文档是项目的知识，这些知识必须集中管理、容易获取、人人可以编辑。
• 项目在生长，代码在增加，文档也必须能够跟随项目自然生长，强行划分设计阶段和开发阶段，是不可取的。
• Wiki不是传统的项目文档，而是一个应交流需要，可能随时增删改的知识库。项目组的成员，遇到问题，就应该首先查看Wiki，如果这是Wiki中没有，那么他应该找人询问。而那个知道答案的人，如果他不想再今后不断的回答同一问题，就应该把这个答案写入Wiki，这就是Wiki条目增长的自然动力。
• 传统文档最大的问题在于浪费，而Wiki通过持续修改，按需提供的方式，保证了所有写下的文字，一定有超过一个人需要读它。

在Wikipedia的基础上，我又做了一些增强，以更好的辅助项目的管理。

• Include功能，增加include标签，可以在一个条目中，引入其他条目的全文，而不是仅仅增加一个link。
• 文档的层次结构，当项目的文档条目逐渐增加，分门别类的条目，更加便于查找，也可以有效的避免条目重名的问题。
• 一个Click，就能够创建新一个条目，用于填写当天的工作安排。

相应的管理制度，也必须建立起来。

• 每日15分钟文档制度，基于“填写当日工作”的功能，我规定每个项目组成员，每天要花三个5分钟来写文档，早上的5分钟，填写当日工作计划。中午的5分钟填写上午的工作情况，下班前的5分钟，填写下午的工作情况。这样，每天的文档工作相当轻松，但是文档能够保证持续的跟随项目成长下去。更进一步的，这样的制度，对于项目的进度控制，也很有帮助。
• User Case条目驱动，所有分解出去的User Case，在分配到责任人之后，该责任人的第一项工作，就是在Wiki中写下对于这个User Case的理解。随后项目进展，也应该持续的维护这个条目。
• 同时进行Bug的管理，Bug也作为Wiki中的条目，以便于和其他条目项目引用。
• 每次Check In CVS时，必须写注释。这是更加细节的文档，然后我还做了一个小程序，能够自动的从CVSTrac中读出当天Check In代码的注释。供每个人在写当天文档的时候引用。

总而言之，我对于项目文档的看法，并不是非此即彼的极端主义者。在我看来，好的项目文档管理政策，应该有助于集中团队知识和智慧，同时不要让程序员痛苦和反感。这样才叫做有效的项目管理。仿造Martin Fowler的著名文献《持续集成》，我给这篇Blog起这样一个名字《软件开发文档的持续集成》，希望能够引发更多的、更深入的思考。

原文写于：2006年05月12日，现在看来，还是很不错的实践啊。