软件开发中文档设计之我见

      在国内很少有IT公司把文档设计列为软件设计的一部份，也许很多是出于开发成本的考虑，因为要做文档设计，则必定要耗费更多的人力和时间，也即要付出更多的成本，我也对此曾经感到疑惑，国内IT公司竞争非常剧烈，时间和成本往往是第一考虑要素。其实，这些都是小公司的通病，很多小公司也因此毁于一旦，主要是因为没有做文档设计使得开发陷入混乱直至最后项目无法交付或无法按期交付，或者因为某些关键员工离开导致项目无法继续开发下去(因为没有文档，交接是非常困难的)，可见急功近利的短见行为只能是害了自己。

       我总喜欢把文档设计作为我在程序开发过程中的一个总结(一个人不去总结自己所做的事，怎么能不断进步呢？)，这个总结也许是在写代码之前来做，也许是在代码写完并充分测试肯定之后来做，因为有时候在没写代码之前无法有思路，当写完代码之后才有思路，这个时候再去仔细地写一下文档，一方面可理顺一下先前的思路，另一方面也可以再次地检查一下先前的思路是否有漏洞，保存下来的文档许久之后再来看时也许还能发现一些毛病，当发现哪里代码不理解时通过文档又可以知道当时的思路是怎样的。

       我的记忆力不是很好(没有过目不忘的超能)，在很久之前写的代码如果逻辑较复杂，我常常会忘记是怎么回事了，我也不喜欢看代码，更不喜欢看别人写的代码，因为每次看代码要死掉好多的脑细胞，我不喜欢在代码中写下拖沓冗长的注释(除非特别必要)，我喜欢干净简洁的代码，因为对有些设计不是三言两语就可以表明意思的。我觉得要了解代码，最好是通过文档去了解，也许看了一天才能理解的代码，但你只要花五分钟的时间去看文档就能理解这个代码了。代码是抽象枯燥的，但文档却是形象甚至是生动的，所以看设计文档是件事半功倍的事，我相信没有一个程序员在有文档的情况下只喜欢看代码而不看文档，除非他是电脑而不是人脑，现在我们花了那么点时间去做文档，也许将来我们能够省下几倍速甚至几十倍的时间。

       文档也是开发人员之间进行交流的很好的工具。就是再能言善辩的人也会忽略设计过程中的某些细节，文档可以让你记下所有细节，而且永不丢失，完备的文档也能够让人更加理解你，特别是图文并茂的文档能够更让人接受你的思路。如果是异地交流，那文档是再也好不过的工具了，而且还可以省了不少的通信费。如果有文档，开发人员之间进行交接也是件非常省心的事，用不着对着代码一行一行地告诉他是怎么做的，有些东西不是代码的问题，如开发环境的建立，如果没有文档，你只好帮人家一步一步地把开发环境建立起来，如果你忘记了其中某些步骤，那就更惨了。

       写文档确实是件烦心的事(特别是对那些写作能力差的人)，特别是第一次写文档确实是件很不容易的事，会让你有无从“下笔”的感觉，其实，我们第一次写代码时也有这种感觉的，为什么现在写代码会象作家写作那样“下笔千行”呢?什么事情只要做熟悉了，就变得简单了，而且现在也有很多文档模板，只要在模板上做填充就可以了，但我不喜欢照搬模板格式，在有些情况下模板是无法套用的，我的原则是只要对自己和对他人适用就可以了，当然严谨也是很重要的，我不喜欢没头没尾罗列式的文档，起码要有个总结，因为对有些人(如你的上司)只要看总结就可以了，他们没有必要也没有时间去详细了解，还有作者、时间、修改日志也都是应该要有的(文档跟代码一样，也有个维护的过程，缺乏维护的文档会害人害已的)。

       说了这么多，最后来考虑一下成本的问题，写文档真的会增加许多开发时间和人力成本吗？我觉得如果严格按照标准的软件工程的思想去做文档设计，那确实会增加许多成本的投入的，对于一些小公司确实是无法承担的，其实那种教条主义的软件工程的思想已经被许多专家所怀疑了，要知道，软件工程的思想到现在还不是个成熟的思想，还有很多问题需要探讨，但有一点是不容怀疑的：文档设计应该是软件设计的一个组成部份，关键在于怎么因地制宜、因时而变，选择一个最适合本公司的文档设计要求，从成本和开发时间上去考虑，文档设计可以做更多的灵活变通的，比如如果没有时间做，则可先记下当时设计的关键要点，等有时间时再完善一下文档的设计。成本问题是灵活并可控的，只要有心，是没有不可克服的。