软件开发最重要的一环 - 文档 (更新）

什么是软件开发最重要的一环？ 从不同的角度可以有不同的观点, 　但如何保证一个执行中的项目在顺利和按时进行？最简单的办法就是检查有关文档.   不然就只能听程序员汇报了。而程序员永远是对自己的进展最乐观的人。他们对软件原型到 产品 的时间的估计往往令人啼笑皆非。 《人月神话》一书中对此有很好的描述，我在 软件开发的两条铁律一文中，也举了一些亲身的例子。一个没有文档或者文档很糟糕的项目一定是一个背后有问题的项目.    所以说，软件开发最重要的一环，但也是最常被忽视的一环，就是软件开发文档，而不是通常想象的Coding.  

世界上没有一个 软件工程师 喜欢写文档.  因为他们常常感觉自己的工作象个艺术家，而不是工程师。这有点象没有一个诗人喜欢逐句注释自己的诗词,   没有一个画家喜欢用文字来描述自己作品的意境.   他们觉得这是多余的，甚至是画蛇添足的。因为他们的作品是不可描述的。或者说，无法有对应的文档的。但是,  软件项目工程已经不再是一门可以随意发挥的艺术,   而是一项必须遵循规范的系统工程.   文档就是软件从艺术转化为工程的一个标志.  这里我们需要的不是朦胧的美,  而是清楚和科学的工程描述。  我比较喜欢软件工程师这个称呼，而不是程序开发员。因为软件项目工程与写程序不是同一个概念。写程序只是软件项目工程的一部分。工程师这个词有很多内涵，它不同于艺术家，也不同于科学家。虽然软件开发可能常常界于三者之间。 但作为一个项目执行者来说，他必须首先是一个严谨的工程师。 软件工程师不喜欢写文档还很多实际的原因.  比如说,   他们可能从来没有受到这方面的训练和缺乏相关实践；写文档像写code一样，不是一开始就能写好的。他们也可能不认识到文档的重要性；有的则可能认为文档是给别人看的,  自己不需要，就懒得写；有的软件工程师甚至故意不好好写文档, 　这样就没有其他人能够取代他们的工作.    跟跨国大公司的老总讨论国内员工的管理，他们说，国内软件工程师最大的问题，一是沟通，特别是英语沟通。二就是不认为他们写的code 是属于公司的，而是属于他们自己的．但如果没有文档， 那么想属于公司都没有办法，因为一切都在他头脑里， 他一走就都带走了。 一般的软件工程师都认为coding  最重要.  当他们当上经理之后, 或者办了几个软件公司之后,   他们才认识到,   没有文档的 code  对公司财富的积累其实没有什么帮助。特别是对做软件项目工程的公司来说。没有好的文档管理的软件公司一定是失败的.   现在网上开源的code 什么方面的都有，但开源的问题就是没有好的文档。许多人认为code 是实的，文档是虚的．其实不是这样的．为什么说文档这样重要呢？ 第一，最直接的原因，有好文档的code　其他人才能看得懂．特别是一些复杂一点的程序，比如编解码器，没有文档如何能在几个月内看懂？除非你以前写过类似的程序。现在反编译工具越来越发达，其实有没有code 都是差不太多的， 特别是对Java这样的程序。. 第二，认真说来，文档与code一样，其实是项目不可分割的一部分。 第三，文档是项目管理的表现形式，是项目与其他方面沟通的媒体，也是项目管理的工具。 软件项目，与程序不再是一个概念。　 我们知道，现代项目管理的概念是从现代飞机制造开始的，现代飞机有几万到几十万个零件，必须有一整套管理方法，管理的体现方式就是一整套相应的文档。 我们知道，一个产品， 比如说医疗设备，要通过美国FDA是非常难的。FDA 除了设备的质量检查以外，更要看你的生产过程及其管理，怎么看，就是看文档。你这个零件是从哪里采购的，有关文档在那里？如果拿不出来，直接就当掉了。 最近在一个软件公司作交接,   意外的发现项目经理竟然不知道他管理的项目实际上是用什么技术来开发的.  不管是否是项目经理真的不懂, 　还是故意忽悠.   如果要这样的事情不会发生,  只有一招, 文档管理.  　 用一个通俗一点的比喻,   没有文档的软件,  就像没有账目的财务.   最后他把钱和原始发票单据交给你就完事,   账目是没有的.   要知道钱怎么用的?  自己去查发票吧．要了解软件的内容？自己去看源代码吧．　 让软件工程师写文档,   常常听到的回答是,  太忙了, 没有时间写,   如果我是经理, 　那我就会让他们停下来,  先把文档写好.  因为我知道项目已经出了问题了。不然的话,  从公司的角度来说，他们只是在浪费时间而已．文档管理好的公司都很难成功，没有文档管理的公司长期来说一定是失败的.  软件项目管理，说穿了其实就是软件文档管理．你能够让工程师写出很好的很完全的文档，你的管理就成功了．　 在美国所有的软件公司，都要求完整的，完善的， 和符合UML 标准的文档．设计文档没有上级签字之前，任何工程师不许开始coding .  除非是必须的 prove concept.  一些软件公司，不但要求完全的文档，有的甚至要求code 全部从Rose 里面生成和编译，以保证文档和code 完全相符．至于要求所有的程序员都按一定的风格来写code,  那就是更高的要求了。 一个很多人参与的长期的项目，文档就更重要了，code 很容易乱的。 我看过一些世界上很通用和很著名的商用软件的源代码，其混乱程度使人吃惊。这样的code后来一定是要重写的。改到一定程度就没有办法改了。 这里插一句，什么是软件公司？ 微软是软件公司。EBA 是软件公司， 但惠普，思科以及华为这样的公司本来都不能算软件公司，尽管他们有很多天才的软件人员，但他们对软件开发的理解和体会是跟真正的软件公司不一样的。 今天，因为估值的原因和软件的重要性，所有的IT公司都把自己称为软件公司了。 　 那软件开发需要什么样的文档呢？具体程序又是怎么样的呢？请听下回分解．