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

发表于:2017-9-11 14:46

字体: | 上一篇 | 下一篇 | 我要投稿

 作者:荣    来源:51Testing软件测试网采编

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

关注51Testing

联系我们

快捷面板 站点地图 联系我们 广告服务 关于我们 站长统计 发展历程

法律顾问:上海兰迪律师事务所 项棋律师
版权所有 上海博为峰软件技术股份有限公司 Copyright©51testing.com 2003-2024
投诉及意见反馈:webmaster@51testing.com; 业务联系:service@51testing.com 021-64471599-8017

沪ICP备05003035号

沪公网安备 31010102002173号