软件开发文档的持续集成

大多数程序员,都极度痛恨写文档。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日,现在看来,还是很不错的实践啊。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 211,743评论 6 492
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,296评论 3 385
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 157,285评论 0 348
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,485评论 1 283
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,581评论 6 386
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,821评论 1 290
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,960评论 3 408
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,719评论 0 266
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,186评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,516评论 2 327
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,650评论 1 340
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,329评论 4 330
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,936评论 3 313
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,757评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,991评论 1 266
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,370评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,527评论 2 349

推荐阅读更多精彩内容