软件开发实践:如何将编码和文档相结合
好像软件开发人员都特别讨厌文档（个人观察，个人观点）。做软件有一大堆文档，例如项目立项报告，需求调研报告，需求规格说明书，概要设计报告，详细设计报告...。文档一大堆，真正让大家仔细阅读，起到作用的好像不多。
倒也不是这些文档没有，其实这些文档的作者都是费很大的心力去完成的，虽然有些段落是文档中模板需要才添加的，有很多套话。但是还是有很多章节是很有用，作者下了很大功夫的， 对开发很有用的。如项目立项报告中对开该项目的定位，市场分析及可能形成的门槛和竞争优势的分析都是很有用的。需求调研报告中的竞品分析，特性识别也是很有用的。需求规格说明书也是开发人员在开发过程中，会时不时找出来仔细阅读，认真去抠的。
但是文档给我们的感觉还是虽然下了大力气写，但是好像效果都不好，性价比不高。
在敏捷开发中， 对文档就不是很重视了。在敏捷开发中， 提倡讲述用户故事，然后就是实现，测试等。敏捷开发提倡源代码即文档。
当时在做了多年的开发后，我发觉适当的文档，对于产品经理，开发者，测试人员之间的沟通，还是很有用的。
最近进行了一次编码和文档相结合的实现，在这里写出来，和大家交流一下。
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，又把时序图加了上来。
这就是我本次的文档实践。
