软件文档--扬弃还是传承 （原文最终修订于 2006-04-12，上午12:41:14）

在本人的《敏捷软件开发：原则、模式与实践》一书中曾提到“Martin对编写文档的第一原则是：除非是必须马上撰写文档而且意义重大，否则的话就干脆不要写它”。有些人把这个意思曲解为敏捷开发一种不需要文档的开发过程，这并不属实。

文档是所有软件开发过程中必不可缺的环节，打着“敏捷”的幌子拒绝编写文档是一种不健全的偏激行径，而且这与那些不假思索就容忍产品中包含十几种不同文档，且自称是“开发过程的终极回归”的说法没什么差别。撰写文档与其它软件活动一样，也需要经过一番投资回报的权衡。我们只会在确实需要文档的时候才编写它，同时编写文档带来的收益也应该是值得其所花费的努力的。

敏捷方法需要两种类型的文档，它们分别是需求文档和设计文档，而其它所有类型的文档都是选择性的。但选择性可不是说就不需要了。

1. 需求文档。在敏捷方法中，需求文档往往会在某次迭代之中进行。它经常先于其他开发过程，但也要到开发过程的迭代开始的时候才在内容上达到完整。此外，它也会被自动化验收测试所用。其它种类的需求文档，像是叙述型、工作流型和图像型文档，可能也会酌情使用。
2. 设计文档。在敏捷方法中，设计文档往往是由测试优先方法指导编写的单元测试所构成的。这些单元测试都是如何使用各部分代码的鲜活的例子。其它种类的设计文档，像是类图、交互图、状态图、ER图等也可能会酌情使用。

文档是开发团队在必要的时候才创建的，当他们觉得需要的时候就编写了它，就这么简单。而且文档在开发团队自身的开发过程中并不需要，往往是客户或市场来决定它们是否需要。开发团队会使用素材卡片（译注）来预估、计划并确定具体完成时间。如果某项素材在迭代过程中并未被加入，那此项素材也一定对客户或市场来说是毫无价值的。而如果加入到了开发计划中，那一定是因为客户或是市场认为它们足够重要所致。

译注：

用户素材，原文user stories。索引卡片，原文index card。为了进行项目计划，必须要知道和项目需求有关的内容，但是却无需知道得太多。需求的特定细节很可能会随时间而改变，因此，在离真正实现需求还很早时就去捕获该需求的特定细节，很可能会导致做无用功以及对需求不成熟的关注。在XP中，我们更愿意客户在索引卡片上写下一些我们认可的词语，这些片言只语可以提醒我们一起这次交谈。用户素材就是正在进行的关于需求谈话的助记符。它是一个计划工具，客户可以使用它并根据它的优先级和估算代价来安排实现该需求的时间。

（原文链接网址：http://www.butunclebob.com/ArticleS.UncleBob.OnDocumentation; Robert C. Martin的英文blog网址：http://www.butunclebob.com/ArticleS.UncleBob）

作者简介：Robert C. Martin是Object Mentor公司总裁，面向对象设计、模式、UML、敏捷方法学和极限编程领域内的资深顾问。他不仅是Jolt获奖图书《敏捷软件开发：原则、模式与实践》（中文版）（《敏捷软件开发》（英文影印版））的作者，还是畅销书Designing Object-Oriented C++ Applications Using the Booch Method的作者。Martin是Pattern Languages of Program Design 3和More C++ Gems的主编，并与James Newkirk合著了XP in Practice。他是国际程序员大会上著名的发言人，并在C++ Report杂志担任过4年的编辑。