软件开发中文档设计之我见

原创 2007年09月17日 14:36:00
      在国内很少有IT公司把文档设计列为软件设计的一部份,也许很多是出于开发成本的考虑,因为要做文档设计,则必定要耗费更多的人力和时间,也即要付出更多的成本,我也对此曾经感到疑惑,国内IT公司竞争非常剧烈,时间和成本往往是第一考虑要素。其实,这些都是小公司的通病,很多小公司也因此毁于一旦,主要是因为没有做文档设计使得开发陷入混乱直至最后项目无法交付或无法按期交付,或者因为某些关键员工离开导致项目无法继续开发下去(因为没有文档,交接是非常困难的),可见急功近利的短见行为只能是害了自己。
       我总喜欢把文档设计作为我在程序开发过程中的一个总结(一个人不去总结自己所做的事,怎么能不断进步呢?),这个总结也许是在写代码之前来做,也许是在代码写完并充分测试肯定之后来做,因为有时候在没写代码之前无法有思路,当写完代码之后才有思路,这个时候再去仔细地写一下文档,一方面可理顺一下先前的思路,另一方面也可以再次地检查一下先前的思路是否有漏洞,保存下来的文档许久之后再来看时也许还能发现一些毛病,当发现哪里代码不理解时通过文档又可以知道当时的思路是怎样的。
       我的记忆力不是很好(没有过目不忘的超能),在很久之前写的代码如果逻辑较复杂,我常常会忘记是怎么回事了,我也不喜欢看代码,更不喜欢看别人写的代码,因为每次看代码要死掉好多的脑细胞,我不喜欢在代码中写下拖沓冗长的注释(除非特别必要),我喜欢干净简洁的代码,因为对有些设计不是三言两语就可以表明意思的。我觉得要了解代码,最好是通过文档去了解,也许看了一天才能理解的代码,但你只要花五分钟的时间去看文档就能理解这个代码了。代码是抽象枯燥的,但文档却是形象甚至是生动的,所以看设计文档是件事半功倍的事,我相信没有一个程序员在有文档的情况下只喜欢看代码而不看文档,除非他是电脑而不是人脑,现在我们花了那么点时间去做文档,也许将来我们能够省下几倍速甚至几十倍的时间。
       文档也是开发人员之间进行交流的很好的工具。就是再能言善辩的人也会忽略设计过程中的某些细节,文档可以让你记下所有细节,而且永不丢失,完备的文档也能够让人更加理解你,特别是图文并茂的文档能够更让人接受你的思路。如果是异地交流,那文档是再也好不过的工具了,而且还可以省了不少的通信费。如果有文档,开发人员之间进行交接也是件非常省心的事,用不着对着代码一行一行地告诉他是怎么做的,有些东西不是代码的问题,如开发环境的建立,如果没有文档,你只好帮人家一步一步地把开发环境建立起来,如果你忘记了其中某些步骤,那就更惨了。
       写文档确实是件烦心的事(特别是对那些写作能力差的人),特别是第一次写文档确实是件很不容易的事,会让你有无从“下笔”的感觉,其实,我们第一次写代码时也有这种感觉的,为什么现在写代码会象作家写作那样“下笔千行”呢?什么事情只要做熟悉了,就变得简单了,而且现在也有很多文档模板,只要在模板上做填充就可以了,但我不喜欢照搬模板格式,在有些情况下模板是无法套用的,我的原则是只要对自己和对他人适用就可以了,当然严谨也是很重要的,我不喜欢没头没尾罗列式的文档,起码要有个总结,因为对有些人(如你的上司)只要看总结就可以了,他们没有必要也没有时间去详细了解,还有作者、时间、修改日志也都是应该要有的(文档跟代码一样,也有个维护的过程,缺乏维护的文档会害人害已的)。
       说了这么多,最后来考虑一下成本的问题,写文档真的会增加许多开发时间和人力成本吗?我觉得如果严格按照标准的软件工程的思想去做文档设计,那确实会增加许多成本的投入的,对于一些小公司确实是无法承担的,其实那种教条主义的软件工程的思想已经被许多专家所怀疑了,要知道,软件工程的思想到现在还不是个成熟的思想,还有很多问题需要探讨,但有一点是不容怀疑的:文档设计应该是软件设计的一个组成部份,关键在于怎么因地制宜、因时而变,选择一个最适合本公司的文档设计要求,从成本和开发时间上去考虑,文档设计可以做更多的灵活变通的,比如如果没有时间做,则可先记下当时设计的关键要点,等有时间时再完善一下文档的设计。成本问题是灵活并可控的,只要有心,是没有不可克服的。
 

软件开发文档范例

对于软件工程学科的同学都知道,软件工程是一门技术含量高设计极其复杂的学科。为了控制好软件产品质量和规范,就必须用大量的文档约束软件工程的进度和状态。浩大的软件工程对于缺少工作和项目经验的人来说,必然是...
  • SunCherryDream
  • SunCherryDream
  • 2014年04月08日 09:11
  • 44592

软件开发文档范例

对于软件工程学科的同学都知道,软件工程是一门技术含量高设计极其复杂的学科。为了控制好软件产品质量和规范,就必须用大量的文档约束软件工程的进度和状态。浩大的软件工程对于缺少工作和项目经验的人来说,必然是...
  • u012467492
  • u012467492
  • 2016年11月28日 11:19
  • 972

软件开发文档模板

 目录1. 范围.... 12. 总体要求.... 12.1 总体功能要求... 12.2 软件开发平台要求... 12.3 软件项目的开发实施过程管理要求... 22.3.1 软件项目实施过程总体要...
  • eaglewood2005
  • eaglewood2005
  • 2009年04月15日 17:13
  • 28482

软件开发详细设计说明书范例

  • 2011年12月16日 20:45
  • 2.28MB
  • 下载

软件开发标准(文档模板)

操作手册(GB8567——88)1引言1.1编写目的说明编写这份操作手册的目的,指出预期的读者。1.2前景说明:a.  这份操作手册所描述的软件系统的名称;b.  该软件项目的任务提出者、开发者、用户...
  • GlroyFuture
  • GlroyFuture
  • 2009年03月16日 14:30
  • 6528

软件开发的过程中,这些文档你都用到了吗?

导读:做软件的目的就是要满足客户的需求,这个需求包括功能、外观、操作、时间及性能等各方面。那么,在软件开发过程中那部分最重要呢,程序员说“毋庸置疑,我编写的程序实现了客户提出的功能以及业务流程,......
  • xuqiang918
  • xuqiang918
  • 2014年04月10日 16:28
  • 8466

软件开发过程文档

  • 2008年04月14日 07:51
  • 270KB
  • 下载

整个软件开发过程所要用到的全部文档模板

  • 2009年08月25日 20:20
  • 109KB
  • 下载

软件开发中的详细设计

传统软件开发中的详细设计: 模块内的数据结构进行设计。比如模块中类、结构体的设计对数据结构进行物体设计。比如数据库表的设计,文件存储的设计,文件存储目录的设计每个模块进行详细算法设计。比如每个方法...
  • wang15061955806
  • wang15061955806
  • 2016年02月03日 17:00
  • 2803

让你提前认识软件开发(40):既要写好代码,又要写好文档

第3部分 软件研发工作总结既要写好代码,又要写好文档         对于软件相关行业,在学校或单位上,大家也许都已经注意到了,除了要编写的程序、绘制设计图之外,还有一个重要的工作便是写文档。为什么要...
  • zhouzxi
  • zhouzxi
  • 2014年07月27日 20:56
  • 1876
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:软件开发中文档设计之我见
举报原因:
原因补充:

(最多只允许输入30个字)