文档那些事儿 .

 

这几天验收系统的时候，我们小组补充了很多文档，这让我想了很多。

l 为什么文档大部分是后补的，或者是做完系统之后做了大量的修改？

l 真正意义上的文档应该什么时候写？

l 为什么很多团队不愿意写文档？

程序员在看别人的代码的时候常常抱怨没有注释，没有文档……但是当自己该写注释或者文档的时候却懒懒的能少写就少写。这本身就是一个巨大的讽刺，一个喜欢注释和文档的人却常常不写注释和文档，俨然就是典型的只许自己放火不许别人点灯的行为。

下面是程序员们不想写文档的种种理由：

“写文档多浪费时间，有这个时间老子七八个类都写完了！”

“写他妈的文档也没有人看，写个磷啊！”

“现在的开发一般都是从零开始，在原有的基础之上开发简直就是自虐，既然从零开始那么就不需要看他们的文档，自己做自己的就行！同理以后别人也不看我们的文档！”

以上理由的根源在于，程序员最不喜欢去读别人的代码，更不愿意调试别人的代码，遇到不通顺的代码常常是ctrl+A然后delete，接下来就是自己创造一片新天地，写完后看着自己的代码，越看越喜欢，越看越喜欢，那真是满心的自恋之情无法言表。

然而一般的项目经理都是从程序员干起的，所以看到别人的系统，别说没文档就是有文档也懒得看。除非用户强行要求，不然绝不会在原来老系统的基础上进行新的开发。就算用户强行要求，项目负责人也会千方百计的告诉客户老系统哪里不好，哪里需要完善如此云云。然后劝客户重新开发新系统，总之就是通过各种勾引，各种“强奸”，各种游说让用户接受一个崭新的与老系统完全没有联系的系统。

遇到负责的项目负责人想在以前的系统之上改进，但是由于文档不全或者以前的设计者已经跳槽，了解没有文档的旧系统简直就是自杀，有那时间还不如从零开始开发嘞！所以这种情况下项目负责人最后只好按照自己的想法重新设计，重新构建，从零开始。他们认为只有这样才能干净！方便！“效率高”！

如此一来人们对文档的重视程度就大大减小了，写了文档没人看，谁还去写呀！然后恶性循环，渐渐的文档就沦为形式了。

我们为什么写文档？

写文档究竟是为了什么，现在大部分的文档写的都很形式，都是做个样子。很多团队都是先有代码后有设计说明，简直就是笑话。完全的形式主义，为了文档而写文档，完全把文档的意义给扭曲了。

l 文档帮助我们进行更好的沟通

这里就涉及到一个问题：文档写到什么程度为好？答案就是合格的文档不需要文笔多么的好，不需要文字多么多，不需要什么特别严格的格式；只需要能让他人看懂，能让他人拿到文档后不需要再向你咨询直接根据文档就能比较全面的了解这个系统，仅此而已。说起来容易做起来还是比较难的。

问过很多团队不写文档的原因，最多的回答就是为了“高效”的完成系统，但是纵观没有文档的开发似乎也并不高效，没有文档的情况下团队中往往充斥着以下对话。

A：我那的接口呢

B：你们要那的接口了吗？没有吧

A：谁说的，****时候不是给你说了我们要****接口了么！！

B：没有吧，不记得了

A：……

假如当时马上能拿出一份文档，那么到底是谁的责任就明确的多了，所谓有文档有真相就是这么个意思吧。况且如果真有文档的话，也不会发生上面的对话了。相信每个开发团队中的开发人员的阅读和理解中文文字的能力还是有的，不至于对照着文档还能落掉哪个方法丢掉哪个类吧。所谓好脑子不如烂笔头就是这个道理，所以说没有文档作保证，高效的交流什么的就是浮云。

l 文档帮助我们记录开发周期的点点滴滴

不要认为以后没有人看就不需要写文档了。

一个优秀的团队应该把每个开发过的项目中用到的东西，例如典型的技术，经典的算法，等等都应该以文档的形式保存下来。因为你的团队不可能只开发一次系统，下次可能开发别的系统但是很有可能用到这次开发过程中的部分技术或者部分算法等等更有甚者或者两个项目业务几乎一致完全可以把以前的架构拿过来用，这都不是不可能的。这样一来文档的巨大作用就体现出来了。

很多的团队没有及时的文档，请注意是及时的文档，不包括代码完成后补充的文档。虽然补充文档要比没有文档强的多，但是补充的文档有很多问题。比如记录工期不准确，记录所用到的技术或者算法不完全，补充的文档非常耗费时间等等。我们能顺手做而且又不得不做的事情为什么要单独拿出来做呢？。

l 文档可以帮助我们整理思路

没有文档需求岂不是之上谈兵。今天说个样，明天说个样，这系统还能做么？

没有概要设计或者详细设计，如果团队整个开发周期中如果人员不流动的话还好一点，人员万一流动就会出现文章前面说的那个情况：ctrl+ A 然后delete接着一群自恋的人就开始开辟自己的一片新世界了。这样的话等待整个团队的将是功能实现上的矛盾，工期的无限延长，但是如果有文档的话情况就大大不同了。

设计人员通过写文档可以对整个软件或者自己的模块有一个比较详细的了解，写文档说白了就是用文字编码。有一句很经典的话：能编码不一定能写好文档，但是能写好文档的一定可以很好的编码。画过UMl图的人都知道，简单的几条线要比几十行甚至几百行代码来的快。同样的道理文档作用也是如此，几行文字要比N行代码来的省事。由于UML毕竟是建模的语言不是真正的人类交流的语言，所以在与用户或者与水平比较低的团队队员之间交流过程中文档的作用就更加明显了。根据文档程序员就能直接编码才是优秀文档最理想的效果。

l 文档可以为我们节约时间

除了上文中说的没有文档的话交流没有合理的记录之外，没有文档的另一个弊端就是非常容易浪费双方的时间。很多团队感觉文档没用，于是整个团队之间最常见的交流方式是qq或者飞信，更有甚者直接口头交流。相互说你要什么接口我需要什么方法，重复的话说的不少，时间也耗费了不少，结果却很难令人满意。

显而易见，没有文档的交流（无论是qq、飞信还是口头）都是需要两个人同时参与的。整个过程如下：在你向别人传递信息的时候大脑是不断思考的，也就是说你是边说边思考，那么你的话必定是断断续续的，而且还很有可能是重复或者错误的。更加可悲的是在这短时间里对方必须等待你思考完毕以及你表达完毕，然后对方才能去理解你的意思，最后对方再把他理解的意思阐述给你听以确保理解无误。在这段时间里对方同样也在边说边思考，和上面的情况类似你也不得不等待他思考以及表述完毕，然后才能给予肯定。

算下来整个过程浪费了很多不必要的时间，如果加入用文档的话将是一个情况。前者把思路理顺后直接用文档的形式传递给后者，在前者写文档的时候丝毫不浪费后者的时间。后者拿到文档后直接理解传递过来的文档，理解的过程中也丝毫不浪费前者的时间。最后双方进行反馈，由于大家都已经阅读过文档相对而言准备的已经比较充分了，所以就可以直奔主题进入关键部分了，为整个团队节约了很多时间，效率自然而然就高了。