该帖子同步发自：(飞眉的博客  访问该博客)

　　我们需要哪些文档，工具和努力

　　软件项目肯定离不了文档和管理工具，如果您的项目还没有它们，那么请从现在开始。那么文档是不是越多越好呢?老话说的好，合适的才是最好的。小而精的文档和工具会让我们事半功倍，大而全的文档会让我们疲于奔命，最后迷失在文档的海洋中。

　　51CTO向您推荐上一篇系列文章：《我们如何开始对项目进行管理：需要什么样的人》

　　我们写代码的都知道，错误的注释比没有注释更可怕;同样的，没有及时得到更新的文档比没有文档更可怕，因为文档就是项目的注释。那么我们是否有必要去更新那些我们根本没有用到的文档呢?很显然，那是非常没有必要的，是对资源的浪费。文档说起来其实就是一个工具，是一个让我们开发时有依据，可以追溯开发过程以及记录开发结果的工具。我们只有用到它，它才有存在的必要。

　　那么文档过于少或者干脆没有文档，不是更简洁?我想说：不写代码不是更简洁?玩笑归玩笑，没有文档或者文档太少会导致的问题大家可能也都遇到过：那就是过程不可追溯，有些非常重要的逻辑没有记录，需要用到时团队成员各执一词，甚至需要重新找客户确认而是客户认为我们不够专业;有些非常重要的设计没有记录，导致代码维护困难，以至于维护人员破口大骂开发人员写的什么垃圾代码做的什么垃圾设计。有些设计非常的巧妙，非常的值得学习，然而就是因为没有留下记录而被初学者如我一样的人骂了N次。在反省自己不够聪明时，是否也该让写代码的人反省一下为什么没能留下点儿记录?

　　有一种观点是最好的设计就是代码，意思是代码就是设计，代码应该非常的优秀，可读性特别好，让人一看就明白，我完全同意。如果代码写到这种程度，那文档就真的没用了。那么请自问，您是这样吗?如果是，没文档，没问题;如果不是，请把重要的东西写下来。那么，哪些是重要的呢?

　　哪些是必须的， 哪些是Optional的。对于哪些文档更重要些，应该由项目的具体情况而定，特别是项目的大小，逻辑的复杂程度，人员的情况等等很多因素。在我做过的项目中，我个人认为最重要的一些文档和工具如下所述：

　　1， 功能说明书(Functional Specification)------按独立功能划分优先级，每一条记录都是一个可交付物，都是一个功能。整个文档就描述了整个项目的交付功能和优先级。项目中的所有人，都应该关注这个文档：测试用它来写测试用例;开发人员用它来决定先开发哪个功能;PM用它来查看功能的完成和验证状态。它通常不应该内容过多(由项目规模决定)，我觉得最多两行字就可以描述一个独立工作的功能，至于对这个功能的理解，应该由负责它的程序员来完成。

　　2， 核心流程图。这个流程图可能描述了用户使用该系统的过程;也可能描述系统中数据的流转;也可能描述表单的流转。总之，它描述一个过程，这个过程对用户来说非常重要。这个图有时候也会被其它的图，如顺序图代替。

　　3， 部署文档。该文档描述了该系统应该如何部署，它不一定非要是一个word文档，也可能仅是一个bat文件而已。这个文档应该描述该项目如何部署，步骤是怎么样的，需要哪些文件，需要哪些硬件支持，以及需要注意什么。部署历来都不太被重视，大家觉得只要东西做出来了，部署不就是放上去吗?其实不然。在经历了一定周期的开发后，开发过程中积累的配置，对环境的要求，在真正部署的时候很多就忘了，所以部署可能会花费很多没必要的时间，我觉得这也是微软要做daily build的原因之一，每天都build一个可用的版本，当然部署就没有问题了。我们刚开始可能不需要每天都build一个版本，但最少要一周或者两周部署一个版本吧。每次部署都整理一个自动化的脚本或者文档，会让你最后上线的时候非常的从容。

　　4， 测试用例。我不是一个测试人员，测试也是我觉得一直没有做到位的地方。客观的说，我觉得用例应该花很大心思去编写，就像用户真正的在使用软件一样。项目应该在设计和开发的时候就以满足用例为目标，而不是开发完了才想起来用例，去测试，发现问题再修改，回头想想，这可能就是测试驱动开发产生的原因吧。我们知道用户发现错误修改的成本高于我们自己发现的错误;同样的，设计和开发阶段就解决的问题成本也远远小于测试阶段发现的。正是，问题发现的越早，解决起来就越容易，成本就越低。

　　5， Bug管理工具。这个管理工具可以是一个excel，当然，我并不推荐这么做，毕竟excel却是不那么自动化。但是，只要比excel自动化一点点儿的信息系统就可以了，它需要可以记录问题，可以传截图，这就够了。我推荐使用bug tracker，这是个dotnet开发的开源的bug管理工具，其实也可以管理需求，是非常实用的。

　　以上五个是我认为最重要的，我觉得是项目开始进行管理的阶段必不可少的;而下面几个，则是大家视情况可选的。

　　6， 核心类图。这个可能是可选的，因为有时候，类的关于没那么复杂，也就没有必要有这个图;相反，则需要进行记录。

　　7， 数据库设计。数据库设计文档可能在review的时候用到。

　　8， 系统间接口图。如果产品有若干个子系统，如web service等等，那么我认为需要一个描述系统间接口和交互关系的图，这个图应该在设计的早期就开发出来供大家使用并且随时保持更新和关注。

　　有了文档和工具，是不是就一切OK了呢?不对，就像大而全的文档并不能帮助我们成功一样，有了文档并不代表项目就能成功，如何维护和使用这些文档和工具是相当重要的。每个文档都应该有人去维护，那么谁去做这个事呢?我认为项目经理应该经常拿着功能说明书开会，它也可以被看做是WBS的初级版本，可以被标注状态和优先级;所有人都应该熟悉流程图，并随时提出对流程图进行检验和review;应该指定一个人负责构建，这并不需要花费很多时间，但是需要细心和一些完美主义精神;测试人员自然要维护好测试用例;每个人特别是开发人员，都应该有一种觉悟，那就是一旦想起了哪些重要的逻辑，不管是业务的逻辑还是系统的算法，都应该记录到bug管理工具上。Bug管理工具完全可以记录这些零散但却重要的东西，以便将来方便查询。

　　在这里我也是根据自己的经历简单的谈了一些我的看法，这并不是金科玉律，我还得说，合适你的才是最好的。

　　(四) 代码规范的选择

　　做开发不可避免的遇到代码规范，从上学时就会学习到一些规范，但是每个公司都不同，那么我们到底要遵守哪些规范呢?我个人认为，一个合格的程序员应该可以随时调整自己适应任何一种规范，这是一种职业素养和能力。而何时该遵循何种规范，这也有一定的原则。

　　1， 在现有系统(代码)基础上进行开发。这种情况下，我们应该尽量的去遵循原有系统的规范，不论是命名还是注释。因为如果这时你非要按照自己的习惯写，那么系统就会出现两种完全不同风格的代码，这对将来的维护是一种噩梦。但是，遵循原有规范不是迁就原有错误。如果发现原有的规范会造成一定的问题，就要立刻改正，不能装傻充愣假装看不见。

　　2， 新建团队开发新的系统。新建的团队中团队成员可能来自不同的环境，对规范的选择倾向一定是不完全一样的，此时要怎么做呢?这时，项目的领导者应该组织大家一起做一个决定，讨论如何定义变量，如何给控件取名等等。在出现意见不统一又谁都说服不了谁的情况时，项目经理应该做出明确的决定。此时选择一种规范远比同时迁就两个人要来的好，不然造成新系统中存在两种规范，同样是维护的噩梦。

　　3， 稳定团队开发新的系统。这种情况就容易得多，团队稳定后团队成员渐渐的了解了互相的习惯，互相学习后就更容易达成妥协。只要注意让新加入的成员适应就可以了。

　　有人可能觉得代码规范没什么大不了，功能正确没有bug不就行了?当然，如果没有bug那肯定没问题，然而一个系统运行到退休还没有bug，哪位见过呢?我做了一些运维工作之后才渐渐了解到，不同风格的代码读起来就像是一会儿在赤道，一会儿在南极，非常的痛苦，有时甚至会造成系统很多的不一致，大大增加了维护的工作量。我们的目标之一不就是增加系统的可维护性吗?