【技术前沿】文档的力量

　　做软件开发要写文档，文档主要起一种说明性文字的作用，为了让用户很方便地使用你的软件，起码要写一本用户手册。当然，有些软件不用需要用户手册也可以直接使用，比如Windows 自带的计算器，往往这类软件在用户点击帮助菜单后，会弹出一个版权信息，这也算是一种文档。大多数软件要比计算器之类的程序复杂得多，所以用户手册一般无法避免。 　

　　针对用户，要写帮助文档；针对软件开发过程，则 要写开发文档。以往开发文档包含软件需求分析、概要 设计、详细设计以及测试计划和测试报告等，所有这些 文档作用是要为开发 人员提供信息来源和 编码支持。随着软件 开发规模越来越大，构 建一个软件成本几乎 和建造一栋楼的成本 相当，在如此规模的软 件开发过程中，正规而 精确的文档的作用则 成为重中之重。

　　有很多程序员意识不到文档的重要 性，特别是在国内， 当然也包括笔者在 内，我们通常认为编 码是第一位，结果最 重要，要交给最终用户能够使用的东西才是王道。纠其原 因，我想是和国内的软件开发环境有关。国内软件售价往 往价格偏低，因为价格低，所以管理人员就会压低成本，一 部分是人员成本，一部分是时间成本。一方面人员不整，所 以没有相关的文档编写人员，或需要编写文档的主要设计 人员忙于编码而忽视文档。况且，一般编码人员，不管其 水平多高，对于编写文档之类的活都避而远之。

　　另一方面项目时间的紧迫性也促使开发人员缩短编写 文档的时间，使得做出来的文档流于形式或表面，根本 起不到对开发工作的指导作用。更有一部分原因，由于 形式主义、官僚主义盛行，文档成为那些政府机关项目 用于向领导汇报的工具，造成的结果就是外行指挥内行，这些文档成为肤皮潦草的报告。

　　我们没有力量改变这种情况，净化国内的开发环境需 要时间，我们能做的就是认识到文档的重要性。

　　举个例子，印度软件出口量全球第一，靠的是什 么？国内接触过印度软件源码的同行告知印度的软件结构 差，不好维护，效率低，代码写得乱七八糟，根本读 不通顺。但有一样不得不让人敬佩，人家的文档写得非 常全，写得非常出色！这就是文档对于一个糟糕项目的维 护能力。

　　另外一个例子就是微软。微软在早起做开发，完全 敌不过其它一些公司 的产品，像M F C、V B 等， 都竞争不过 Borland公司的同类产 品。但看现在怎么样， Borland公司只能靠给 微软维护Delphi度日。 造成这种情况的原因 是微软的开放文档策 略，微软提供多达几个 G的开发文档供开发人 员参考，同时还提供源 码级的开发组件给合 作伙伴，共同为用户开 发产品。比如微软提供 VBA-SDK开发包以供软 件开发商将自己的产品嵌入二次开发的能力，仅这一项就 拉拢像AutoDesk这一级别的战略合作伙伴，其它公司靠什 么来竞争？

　　文档如此重要，正确地规划文档所要编写的内容就成 很重要的事。文档不仅要体现整个软件的结构，还要体 现它的任何一部分细节的构建思路，要做到这一点，以往的做法就是做两个文档，一个是概要设计，一个是详 细设计。同时，为保证软件的质量，还需要写测试文档 等，这种做法目前在大型项目上还是比较流行。

　　目前国际上流行一种新的软件开发流程，称为敏捷软 件开发。该软件开发流程以全新的开发宗旨与理念给开发人员以耳目一新的感觉，敏捷开发的主要倡导者之一提出一个观点：一份过于详细的设计文档是腐朽无用的， 真正有价值的文档是整洁流畅具备很高可读性的源代码。

　　此大师指出一些常见困惑的来源，即我们为什么不爱写设计文档，是因为我们写出来的文档价值不像最初所设 想的那样。这些文档要么流于形式，要么与最终构建的 软件大相径庭，有时不得不花费大量的时间来修改设计文 档，使得文档与已构建完成的软件相对应。大师说，编 写完成的设计文档无法与变化无常的需求相适应，因此腐 朽，唯一能快速响应变化的文档就是源代码，一份结构 清晰，意义明确，带有适当注释的源代码就是一份很好 的设计文档，这份文档必然要与变化的需求相适应。

　　这位前辈也是倡导代码整洁（泛指代码口语化）的 大师之一，从英语条度来看，他给出的规范源代码读起 来非常通顺，像读一篇英语文档。当然目前国人看起来 还是比较费劲，不如一份中文设计文档读起流畅。

　　除了设计文档外，软件开发过程中为保证软件质量还需做测试文档。在传统的软件开发流程中，在做完详细 设计之后，就需要着手制订测试计划，最后测试完成之 后，还要编写测试报告，这一块更容易变成表面工作， 成为程序开发人员的负担，虽然测试文档同样非常重要。

　　 当面对本身就具备“腐臭气味的详细设计文档”时，根据它来制订的测试计划就更不能说得上新鲜。因此众多敏捷开发流程中出现一种叫做测试驱动的开发流 程，即在正式开发软件之前先要开发测试程序，在该测 试程序的支持或者叫做监控下再来开发正式的软件。这无 疑是比较极端的控制软件质量的方式，何时可以使用以及 如何使用仍需要项目管理人员仔细斟酌。

　　 总而言之，文档对于软件开发来说其重要性不言而 喻，如何界定文档内容，如何规范文档内容，如何恰到 好处地编写文档，更有力地为软件开发服务，就成项目 管理工作中最重要的一环，值得大家仔细地思量。