软件开发实践:如何将编码和文档相结合

好像软件开发人员都特别讨厌文档（我的观察，我的观点）。作软件有一大堆文档，例如项目立项报告，需求调研报告，需求规格说明书，概要设计报告，详细设计报告...。文档一大堆，真正让你们仔细阅读，起到做用的好像很少。

倒也不是这些文档没有，其实这些文档的做者都是费很大的心力去完成的，虽然有些段落是文档中模板须要才添加的，有不少套话。可是仍是有不少章节是颇有用，做者下了很大功夫的， 对开发颇有用的。如项目立项报告中对开该项目的定位，市场分析及可能造成的门槛和竞争优点的分析都是颇有用的。需求调研报告中的竞品分析，特性识别也是颇有用的。需求规格说明书也是开发人员在开发过程当中，会时不时找出来仔细阅读，认真去抠的。

可是文档给咱们的感受仍是虽然下了大力气写，可是好像效果都很差，性价比不高。

在敏捷开发中， 对文档就不是很重视了。在敏捷开发中， 提倡讲述用户故事，而后就是实现，测试等。敏捷开发提倡源代码即文档。

当时在作了多年的开发后，我发觉适当的文档，对于产品经理，开发者，测试人员之间的沟通，仍是颇有用的。

最近进行了一次编码和文档相结合的实现，在这里写出来，和你们交流一下。

1 概述

最近作了一个小功能。代码作完后大约有800-1000行左右（C程序），功能比较独立， 并且是有一个后台需求， 没有UI。我尝试在开发这个功能的过程当中写文档。

这个文档是按照本身的理解写的， 没有套用任何模板。最开始也是本身使用的，做为整理思路的工具。该文档后来也用于与产品经理及测试人员沟通。本身以为效果还能够。经过该文档，与产品经理澄清了一些本身认识不正确的地方。 该文档给测试人员提供了帮助，并且能让测试人员尽可能的了解了需求和设计。

2文档内容

2.1需求整理

首先是关于需求的整理。由于只有理解好需求才能开发出正确的软件。怎么算是理解了需求， 写出来，并于需求相关人员达成一致，才能算理解了需求。

之前常常会遇到开发人员本身觉得理解了需求， 下手开发，开发完成后才发现和需求人员理解的不一致， 甚至需求人员理解与客户的真正需求不一致的状况。因此上来我就对需求进行整理。

到这儿，可能你们会头大。用瀑布式开发流程下，写过需求调研报告和需求规格说明书的人知道，这些都是大工程，工做量大，并且预期效果也很差。

在这里，我没有按照之前的需求规格说明书的思路整理需求。而是采用敏捷开发中的用户故事的方式来写。

2.1.1用户需求

用户需求按照以下样式写的：

做为一名...，我但愿...， 以便于...。

这里没有之前需求规格说明书中大写繁琐的部分，只是简单的一句话，当时颇有用。若是你没有写过，很是建议你试试。

该段文字信息量仍是比较大， 并且每一段都是很重要的，根据优先级有大到小：以便于>做为一名>我但愿。

关于这句话，简易看看《软件需求 第三版》的相关章节，写的很好。《敏捷革命》的第六章中的“不要盲目执行任务， 要领会用户故事”对这个句子也有精彩的描述。

关于这部分，个人建议是：

不要超过5条，若是超过条，请仔细反思一下，是否是对需求真正理解了。（个人前提是一个较小的功能）。

关于这部分，在个人实践中， 最开始以两条（实际用户和维护人员）， 后来又一次识别出了一条（工厂模式的测试人员）。

2.1.2功能需求

有了用户需求后， 须要将用户需求细化为功能需求，也就是功能点。简易用下面的语句：

A应该...。

我本次的实践中，功能点共6项， 包括“该功能应该提供完善的日志，以便于在出现为你的时候，经过日志能快速定位问题”和“在系统重启后，日志不该该丢失”等。其中多数是在开始时识别出来的，也有后来添加的，例如工厂模式下的特殊处理。

2.1.3限制，依赖和假设

在咱们的功能开发中，实际上是有不少限制，依赖和假设的。不少时候，咱们会把这些依赖和限制记在内心，这是不够的，咱们须要把它们写出来。这些对咱们开发人员，测试人员和需求相关人员都颇有用。这些限制，依赖和假设要获得需求人员的承认，测试人员的理解。在编码时候，咱们甚至须要把这些做为注释放在代码中。

2.1.4总结

关于需求的整理，须要获得需求人员和客户的承认，开发人员保证真正的理解（个人理解： 在用户需求中，能真正明白“以便于”部分和“做为一名”部分，就算是真正了解了）， 测试人员应该深刻了解这些内容，才能知道功能的前因后果，写出正确的测试用例。

在个人实践中，这部分的文档其实很少， 应该只有半页多一点的文档。

 

2.2需求测试用例

根据需求编写需求测试用例，我是站在开发者的角度写的测试用例，目标就是覆盖需求中的功能点及其各类状况。格式比较随意， 主要是能把这些功能都验证了，没有落下测试点。

在本次实践中，我共编写10条测试用例。

这些测试用例但愿能获得测试人员的评审。

其实测试人员未必会直接用这些测试用例，可是能给他们很大的辅助。本次实践中， 测试人员对这些测试用例仍是很关注的。

2.3设计

主要是记录下设计中的想法和思路。在本次实践中， 我画了一张关联图，主要用来标识该功能中， 系统与哪些外部对象交互，交互了哪些信息。而后用一些文字表述了实现的基本思路。

本次实践中，设计部分大约占半页， 包括关联图。

2.4 设计测试用例

针对设计设计的测试用例。这一块也须要测试人员评审。 可是这块测试主要是我本身使用的。由于我以为一个功能发布出去，最好本身能作以便FT测试。

本次事件中，设计的测试用例大约有*项。

2.5实现

这一部分主要是给代码Review的人看的。由于我以为让别人给本身Review代码，只提供一个ReviewBoard或diff文件，不是很好。

在本次实践中，我提供了一个时序图，并在发出Review请求的时候，将该文档做为附件也发送了出去。

若是是用面向对象编程，我可能会提供一个类图及一个类列表，在类图中表述类之间的关系，在类列表中，描述一个每一个类的功能及想法。

3总结

以上是本身本次实践中的文档。我的以为对本身的开发颇有帮助，并且文档的规模也不大，维护成本也不高。

该文档将客户和需求人员，开发人员，测试人员以及代码Review人员都涉及到了。

此次实践实际上是我看了《软件需求 第三版》后的一次练习（项目是个正式的项目）。

最开始是从需求部分开发的。

虽然已经有需求人员整理了需求，可是没有表达为文字。鉴于之前常常出现开发人员对需求的理解与实际不一致的状况，我就对需求按照《软件需求 第三版》说的作了整理（笔者有十多年编写需求规格说明书的经验，可是总以为之前在瀑布发下写的需求规格说明书并很差，主要困惑容易在需求规格说明书中包含过多设计），而且发给相关人员看。

获得承认后， 又以为既然功能明确了，能够尝试让本身站在一个测试者的角度看，该怎么测试， 因而有了需求测试用例相关部分。

由于到这时候，文档仍是很小，因此我就把设计及设计的测试用例都放在一块儿了，做为本身使用的文档。

在编码完成后，考虑到方便别人Review，又把时序图加了上来。

这就是我本次的文档实践。