编写文档真的是在浪费时间吗?

我最近留意到,在敏捷开发中存在着一个广为流传的谣言——“敏捷中没有文档”或者说“编写文档就是浪费时间”。特别是在从瀑布式向敏捷转型的过程中,我们感受到典型敏捷实践给我们带来的好处,例如:短周期的迭代、时间盒、每日站会、回顾会议等等。这也导致了我们希望放弃在应用敏捷之前的一些习惯:编写文档、给代码加注释等等。但是,我们完全不写文档和注释真的是对的吗?

让我来和大家分享一下我对这方面的经验吧。

我曾经是一个刚转型成敏捷的团队的Scrum Master。在三个sprint之后,我们准备要进行第一次的产品发布,于是我们决定和售后团队举行一个会议来向他们介绍这次在产品中的变化(在这个公司中,开发和售后团队是分开的)。在那次会议中,我们就文档的问题进行了大量的讨论。售后团队希望能够有一些文档(至少是概括性的)介绍产品的架构和他们也希望在代码里面有一些注释能够帮助他们更好地理解业务逻辑。

最后,我们就如何解决这个问题达成了协议:
Scrum团队将会举行一次会议,在这次会议中会非常详细地向售后团队介绍所有的新特性以及架构方面的变化,也会解答所有关于复杂逻辑的代码的问题。
Scrum团队中的其中一个开发人员和售后团队中的一员呼唤角色。这样就能够使售后团队更独立地工作。

这样看起来不错,不是吗?这种办法持续了15个迭代都没有发生任何问题。很多新的特性都已增量的方式加入到产品当中,期间还进行了一些代码重构。

然而,有一天出现了一个特别的业务需求。我们需要开发一些只被特定的一些用户使用的定制特性和功能。在进行了大量的分析之后,团队决定建立一个独立的组件(一个现存组件的复制),然后在上面加上这些定制的功能,而且这个组件也可以被添加到现有的系统上面。于是,我们创建了一些松耦合的组件来避免增加现有组件的复杂度。其中有一位开发人员同时参加了原始组件和定制组件的开发。到目前为止还是合理的是吧?

实际上,由于那个组件有大量的复杂逻辑,那个开发人员花了足足一个多星期才能够完全明白他在一年前写的代码。到最后在经历了测试和修复了一系列测试中发现的问题之后,那位开发人员终于成功地完成了所有需要的修改。

我们就这个组件的开发和部署举行了一个专门的回顾会议。我们得出的最重要的结论如下:

1、负责开发该组件的开发人员为自己花了一个星期才搞明白自己一年前写的代码感到愧疚。这导致了积极性的减低。
2、为了弥补,这位开发人员花费了大量的经历(也就是说给了自己巨大的压力)来完成这个组件的定制。这导致了他遗漏了一个很细微的代码逻辑,从而最终出现大量的BUG。换句话说,结果是低效和低质量的。
3、我们对“在开发过程中不添加注释”和“在一年后花大量时间读懂代码”进行了成本-收益分析。我们发现在开发过程中,程序员写一段注释可能要花费10分钟的时间,但是这样能够另他在以后更加迅速地理解这段代码(也许就是30分钟,而不是一个星期)。
4、最后,团队同意编写最小量的文档和加入最少的注释来避免同类情况再次发生。

最后,我们明白了在敏捷开发中,我们需要的是最少量的文档,而不是完全没有文档。文档的数量需要根据实际情况由团队自己来决定。

我希望我们的这些经验能够帮助其他人更好地前进。我希望大家能够分享自己在这方面的经验以及敏捷相关的想法。