一.简介软件开发一般包括需求分析、设计、实现、测试等过程。开发过程中伴随着对开发文档的编制。由于行业或项目特点的需要，一般组织在基于CMMI或A制定的体系文件，对文档有较高的要求。如何编写开发文档？到底应该写些什么？写到什么程度？各文档之间以及它们和设计、测试等工程和管理活动之间的关系是什么？如何恰当地体现这些关系？编写完成以后的文档如何使用和维护？如何使这些文档发挥作用的同时，不成为软件开发过程中的负担和障碍？这些问题在软件开发过程中比较难于把握，处理不好会降低开发效率，给软件工程师的开发工作带来实际上的困难，同时也不利于项目管理、评审和审核等活动的顺利开展。对软件工程师来说，编码、测试是软件开发必须的活动，这方面大家是有共识的。然而对软件文档的作用，甚至编制文档的意义存在疑问，一些观点甚至以敏捷方法为依据，给开发和管理都造成不少困惑。本系列说明针对这些问题，以实际开发中经常遇到的问题为线索，结合案例分析和问答的方式，对软件研制任务书、需求规格说明、软件设计和测试相关文档的编写进行解释和说明，希望对实施具体开发工作的软件工程师有所帮助。二.文档的作用为什么要编写文档？理解才会产生兴趣，有兴趣才会出有价值的文档，才不会成为负担，不感觉累。（1）为自己写：如同给代码写注释一样，文档首先是为作者自己而写，可以帮助理清关系、启发思路、加深认识、提醒回顾和备忘。从这个角度来讲，写文档和写代码一样，都是软件开发必须的工作。“没有文档行吗？”除非软件功能简单、规模小，此时，注释也是”文档“的一种表现形式。“有经验或高水平的工程师可以不写文档吗？”有经验的工程师维护万行规模的代码的确不会感觉吃力。但是除非你一直维护这些代码，不去做其他工作，否则不借助文档（广义文档，包括任何正式和非正式的记录和说明等）一段时间以后重新看这些代码的时候会感受到困难。“我已经习惯了这种开发方式，的确不需写文档？”参照上面”广义文档“的定义，如果这些也不需要，意味着你在软件开发方面（也包括个人能力）还有较大改进和提升的空间。如果适当规范开发过程，可以提升工作效率。毕竟人有天生的弱点，只是通过在头脑中的模型构造，辅以不断对代码的修改、迭代的方法，不符合（已被证明更有效的）软件开发规律。理解好”广义文档“这个定义。即使采用所谓“原型开发，先完成了代码和功能，一般也存在一些非正式的记录和说明，比如沟通记录、笔记本上的图形和描述、对数据手册和参考设计的理解和记录等。这些内容都在”广义文档“的范畴内。如果对这些内容加以适当整理和总结，就会成为很好（有效）的开发文档。因此，编制”文档“是软件开发过程中必须的活动，绝对不需要”文档“的软件开发过程几乎是不存在的。最后，写好文档是工作认真负责的体现，是个人职业素养的品牌”。文如其人，工作如生活，持这种工作水准的软件工程师受人尊敬。（2）为相关开发方写：完备清晰的文档是成功开发的关键。几年前，我参与了一个通信类项目的开发，芯片的选型决定着整个研发方案甚至开发人员的确定。除了以FPGA为主的开发方案外，基于DSP为主的方案有两个，使用TI公司的KEYSTONE架构的DSP，或另一家公司相应功能的芯片。在方案论证过程中我们果断地选择了前者，其中主要的考虑就是文档的完备性。在这方面，TI是一家值得尊敬的公司，他们的文档细致且完备，对于一个小公司来说，选择这种新的、国内几乎没有多少用户的开发方案，又不能指望厂家直接提供帮助的情况下，依靠的只能是它们的文档。文档是与伙伴交流的界面。敏捷开发提倡有效地当面沟通，但不幸的是我们的交流伙伴经常是跨部门（甚至不在一个地区），即使处于一个部门，设计与测试也常常由不同人来承担。一份好的文档是绝对必要的，否则你就要和伙伴坐在一起工作了。特别是类似第三方测试的情况（对方往往跨越距离甚至处于另一个城市），对方是依据你的设计或需求规格说明来开展测试的，如果提供的文档不完整，或者文实不符，可想而知，测试也不会顺利。当一个个电话打来向你寻求帮助，而你手上还有很多其他工作，分身乏术的时候，一定会为当时没有好好写文档而后悔不及。软件开发是一个持续的活动，生命周期较长，运行维护、修订、升级是一个长期的过程。如果没有一些文档的辅助会给新加入的成员带来困难。从这个角度上看，良好的文档可以使工作交接更加顺利，也使得原来开发者可以更加顺利地开始新的项目或其他工作。我们在工作中也经常遇到过这样的情况，急于完成功能，追赶进度，放弃文档和过程，一旦遇到变故，新接手的工程师对代码不理解，又得不到帮助（根本没有留下文档），只能推迟研制进度，严重时可能造成项目失败，和之前“急行军”节省的时间相比，得不偿失。造成这种项目信息”失传“的主要原因就是对文档和过程的忽视。（3）为组织写：软件开发的结果是组织的资产，这些资产也包括开发文档。用的术语讲，这些都是组织资产库的一部分。如果是组织（乃至更高层面）的重点项目的一部分，其标准和要求也是可以想象的，这也是我们承担此类项目的软件工程师应尽的义务。（4）为客户写：客户（广义客户，包含上下游伙伴，也包括项目的利益相关方）是我们的衣食父母，他们需要了解和评价产品的质量，文档审查是评价的重要手段。
赞赏