现在的位置:首页 > 软件开发行业资讯 > 文章详情

滨州软件开发技术文档

一、滨州软件开发对自己有帮助
滨州软件开发技术文档首先要对自己的工作有帮助,这是评价文档质量的第一原则。
二、对相关开发方有帮助,评审和检查的效果好
技术类文档必须保证“内容完备、描述准确”。文档完成以后要经过检查,关注细节,不要留下名称标识错误、语句矛盾、章节错乱等初级问题。
文档是对作者工作的展现,相关开发方在浏览文档的同时也是在和作者交流,在检查(review)作者的工作。通过文档把自己的工作清晰地展现在读者面前,有助于尽早发现和解决工作中的问题和缺陷,这种浏览和反馈的过程对产品质量的改善有很大帮助。
三、文文一致,文实一致
“文文一致”包括两方面:文档自身的一致性、文档之间的一致。文档自身的一致性是要保证文档内部的名称、标识及内容描述等方面要保持一致。
随着项目的进行,需求和设计逐渐清晰,产品逐渐确定,此时要注意维护文档,使文档自身、文档之间以及文档和最终产品之间保持一致。
四、简单的才最好
滨州软件开发技术文档要保持简洁是文档编写最重要的原则。
a. 描述范围适当,层次不重叠:
模版是一个全集,适合各种类型的项目,在文档编制过程中要针对自己项目特点,选择适合的方面进行描述,不要生搬硬套,没有的章节和要求写无。
软件开发基于还原论的原则,对于复杂和难于处理的大问题,进行逐级的层次化分解,形成简单、清晰、可处理的小问题,最终逐级集成以后,最终完成大问题的解决,软件文档就是在这样的分解和集成过程中形成产物。各个文档之间存在层次关系,文档内部各部分之间也存在层次关系,各个层次之间都有对应的描述范围,不可跨越各自的范围进行描述。同一对象在不同文档中描述的侧重点不同,例如,“需求”在任务书中的描述是比较概括的,这些需求在需求规格说明中来进一步“规格化”。概要设计重点是“结构”设计,过于关注模块的细节会影响对架构的描述,也会对详细设计产生限制。这些关系处理不好,会导致文档之间以及文档内部描述层次上的重叠,前面文档的内容挤占了后续文档的编写空间,甚至造成后续文档编写困难。
针对具体项目,确定范围和层次,超越范围和层次的描述不但影响文档的质量,还会带来不必要的、大量的维护开销,这是造成文档不被使用,进而不能发挥其作用的重要原因之一。
b. 描述程度不要过分细致:
解决了上述范围和层次问题后,剩下的就是描述程度的问题了。有的大纲对内容完整性的要求是“不需要参考其他文献来理解需要实现的内容…..”,也时常听到类似这样的要求----“详细设计应该写到可以直接编码的程度…..”。文档到底要写到怎样的程度?详细设计写成几百页够不够?几千行的代码要写上千页的文档吗?这些问题常常给开发人员带来困惑。在实践过程中发现,文档写的过于细致是很难做到的,效果也不理想。
过分的细致不符合软件的开发规律,也是很难做到的。软件开发是在工具(也包括文档)的辅助下、以人的脑力活动为主,在经验和实践的基础上,不段迭代完善的过程。头脑里运转自如的流程要想清晰地表达出来的确需要一些功夫和技巧,有时候费力强调而写出来的东西在后续设计和实现中发现没有价值。这是开发复杂系统的基本规律所决定的,在对问题没有一定程度的细分,没有获得足够多信息的情况下,过度追求准确性是困难的。
软件开发是一个有时限要求的工程活动,追求“详细”“精确”和开发效率之间要取得平衡。可以采用这样的折中方法----把有限的精力花在架构或较高层次上的对象上去。在结构化设计思想的指导下,只要架构是科学合理的,较低层次的细节即使存在问题也是局部的,一般不会造成严重的影响。 例如,对于一些功能相对简单或时间进度紧张的软件,可以在完成概要设计之后直接进行编码实现。
文档的作用是有限的,不要过分强调其作用而忽视(或不承认)其他因素的作用。编程语言也是一种“语言”,而且是一种逻辑上更严谨,更形式化的语言。编程语言形成的是最终的工作产品,而文档的作用只不过是对最终产品进行解释和说明。对于某些管理者(非软件出身)来说,必须通过文档才能理解代码,因此对文档的细致程度提出过度的要求(他们可能认为只有通过文档才能理解代码),但是对于工程师来说,注释良好的代码本身就具有可理解性。近年来,随着软件行业的整体发展,一些高效的软件工具(如需求管理工具、完善的图形化集成开发环境等)对软件结构和细节的理解、梳理和管理方面也起到很好的帮助作用,而且对于一些较大规模的软件,这种方法要比通过文档理解软件更加高效。
c. 滨州软件开发技术提示避免文档内容重复:
含义或内容上不必要的重复是文档编写常见的问题。重复常常出现在文档之间和文档内部。有关联关系的文档之间内容应避免雷同或重复。恰当地引用可以简化描述,如果一个地方描述过了,其他地方可以引用。不必要的重复也会给修改、检查和维护工作带来麻烦,很容易造成修改遗漏而引起文档的不一致。必须减少由于文档之间内容重复而引起的文档连带修改,特别是对于受控后文档的变更,还存在较大的管理开销,这种连带的修改和变更是不必要的;文档内容的合理安排可以避免含义相同的内容在不同的章节出现,适当的语言运用和恰当的文档编写技巧(如问题提出的方法、语言的含义层次等)可以降低文档内容之间的关联关系,给文档的编写和维护带来便利。这些方法和技巧将在介绍具体文档编制章节中做详细说明。
d. 保持描述的逻辑性和简洁性:
工程类文档应保持语言描述上较好的逻辑性,特别是对上层条目的描述,好的逻辑性和形式化简洁的语言叙述方式,便于读者理清被描述对象的结构和脉络,也使文档的篇幅得到缩减。要采取形式化和简洁的描述方式,首先要求对语言元素进行清晰的定义和描述,例如,定义必要的术语和缩略语,名称要简单且易于理解,标识和类属要清晰规范。由此也显示出定义名称、标识、术语、缩略语的重要意义----它们可以使一系列文档(包括前后有关系的文档)得到简化,使整个开发团队(在开发过程中)的语言表述保持统一有序。

想要了解更多详情欢迎来电咨询18678812288,或登陆网址www.jnwzjs.net。联系人:王经理。