posts - 59,  comments - 323,  trackbacks - 0
  大多数程序员,都极度痛恨写文档。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起这样一个名字《软件开发文档的持续集成》,希望能够引发更多的、更深入的思考。
posted on 2006-05-12 14:23 读书、思考、生活 阅读(28451) 评论(3)  编辑  收藏


FeedBack:
# re: 软件开发文档的持续集成
2006-05-12 15:12 | Harryson
文档和代码都很重要,都来个持续集成.  回复  更多评论
  
# re: 软件开发文档的持续集成
2006-05-12 22:24 | shooper
好文  回复  更多评论
  
# re: 软件开发文档的持续集成
2008-08-26 14:05 | ezpj
不错的想法~   回复  更多评论
  

只有注册用户登录后才能发表评论。


网站导航:
 
<2006年5月>
30123456
78910111213
14151617181920
21222324252627
28293031123
45678910

常用链接

留言簿(20)

随笔档案

友情BLOG

搜索

  •  

最新评论

阅读排行榜

评论排行榜