新闻动态

  当前位置: 首页  新闻动态 >

为什么我们要写软件开发文档

为什么文档是软件开发中的一部分?

计算机本身能够执行符合逻辑的指令,我们在开发过程中只要按照严格的语法和严谨的定义编写代码,那么计算机就能够执行。但是程序能够执行就完事了吗?在软件行业流行这样一句话,代码是让人看的,机器只是顺便执行下。

我们在编写代码之前或者在编写代码过程中,甚至若干个迭代后,文档都是必不可少的,即使你写的软件是给自己用的,也不例外,因为记忆的衰退会导致人-作者失去对程序的了解,你不得不重试你劳动的各个细节,浪费很多不必要的时间。

对于公用的软件,我们通常会远离软件的作者,对于这类软件,文档本身的重要性,更是不言而喻了。

对于一些匿名的软件作品,如果存在 “简约” 的文档,当我们看到这个文档会不禁谩骂,因为即使是一个设计卓越的产品,如果没有完善的文档,对于用户来说,可能是无法延长其生命周期的。

所以对于软件编程产品面向计算机的代码和面向用户的文档是同等重要的,我们克服我们的惰性和压力,坚持完善文档。

文档应该怎么写?

文档大致可以分为三类:

- 使用人员

这部分文档通常要说明软件应该怎么操作,最终达到什么目的,大多是从交互的层面进行软件可以做什么,怎么操作,通常采用说明,和图文并茂的形式进行书写。

- 验收人员

这部分人通常拿到这个可用的软件之后,要保证这个软件是可用的,什么才是可用的呢?

通常我们需要准备以下三个方面进行验证软件的可用性。

1. 准备一组正常的数据,通过跟软件交互进行验证,在正常操作下,软件是可用的。

2. 准备一些边界数据,在输入的情况下,能够合理的提示或者引导用户,进行合法的提示。

3. 准备一组异常的数据,或者不符合要求的输入。在这种情况保证软件不会崩溃。

- 修改人员

通常这部分人对软件的认知程度,相比上面两种要更加深入,因为他要肩负着修改和定制软件内部业务逻辑。对于这一部分人我们在文档中说明以下部分:

1. 需求文档,软件的开发背景,需求分析,框架等文档。

2. 接口文档,以及重要或者复杂业务逻辑的流程图。

3. 代码(清晰的代码逻辑结构,完善的测试用例,以及文件标题以及函数内部应有的注释都是非常重要的。)