项目文档编写规范与代码规范

往往越是规模大的公司,其项目工作中的每一个环节都有相应的规范进行管理,这些规范都是都前辈呕心沥血,披荆斩棘所获的的经验总结,而非普通文书工作者的推猜可得。

       当然,如果刚刚创业起步的小公司如能更早的抓住项目规范、文档规范,更是使公司发展或者比大公司更大的推动力。

       做文档应当十分注意细节问题,可以文档的细节规范决定文档的成败,正所谓细节决定成败。
        1. 首先,绝对不允许有错别字。
        2. 文档标题:命名标准为:客户公司名称+项目名称+版本号。(××公司采编项目_V1.0 )。
        3. 文档属性:打开word文档->文件->属性 (标题、作者、单位)。
        4. 首页:文档标题,客户公司和实施公司LOGO,左下角标注(实施公司名,作者,更新时间,版本,文档编号)。
        5.文档管理:修改记录,审阅记录,分发记录,致被分发者。
        6.目录:动态更新目录,任何栏目修改都要及时更新。
        7. 项目编号:整个项目编号撑起了整篇文档的栏目构架,在视图->文档构架图中应可以看清这个脉络。
        8. 文档字体:文档的项目编号、正文、注释 都应有相应的字体大小。
        9. 图片表格:每个图片和表格都必须要编号。
        10. 段落:段落的之间的行距,是否空行,紧密程度应当十分注意,影响整体美观。
        11. 页眉和页脚:页眉,左边是实施公司LOGO,右边是文档标题;页脚,左边有公司名及版权声明。

     拥有准确技术文档不仅对于公司是非常有益处,而且也能够让客户从中受益。由于产品如何使用在某种程度上是要依赖技术文档来进行说明,因此技术文档必须十分准确可靠。使用不准确和已经过时技术文档对于公司发展也会产生一定阻碍,同样,它也会对公司客户们产生消极影响。一旦客户发现在他们使用产品时候遇到了问题,却不能通过求助于伴随产品技术文档手段进行解决时候,客户们就会对这种产品产生怀疑乃至于失去信心,那么,公司信誉和利益自然而然就会受到损害。这就是不准确和过时技术文档给我们带来危害。

  缺乏准确性以及内容晦涩难懂都会让开发新手以及其他一些技术工作者们对这些技术文档敬而远之,从而不利于他们学习和掌握。在本篇文章中,我们要讨论就是如何在你开发小组中编写出准确而且易于掌握技术文档。

  技巧一:制定出一个技术评价核对表

  许多程序开发设计者以及管理者都缺乏从技术上评价一个文档经验。这里有一些方法可以提高这些技术文档准确性:

  把注意力集中于技术事实上,这样能够核实这些技术是作为技术文档而被编写出来。技术评论工作并不等同于一般编辑工作。

  一定要从技术上核实,在技术文档里编写程序与步骤准确性。

  一定要从技术上核实,在技术文档中使用图片捕捉准确性。

  技巧二:一定要在技术文档编写过程中明确责任

  技术文档编写不一个原因常常是由于对它不够重视。这是由于在编写技术文档时候,没有十分明确各种责任。因此,一定要在技术文档编写过程中明确责任,这些方法包括:

  在技术文档中加入作者以及相关人员姓名。一些公司可能有规定,禁止出现员工姓名,但是在技术文档中包含作者以及相关人士姓名做法能够促进这些内部员工之间交流。对于外部文档使用者,比如为商业现货软件编写用户指南,可以加入作者以及相关人员姓名,用以明确和承认他们对开发所做工作和贡献。

  把文档技术评论作为提供给开发设计人员年度评论一部分。

  在项目计划中指派专人负责技术评论工作。

  技巧三:增加技术文档编写者准确性
  由于技术文档编写者在许多公司内都是非常主观一个职位,并且编写技术文档也是他们最主要职责,因此做这些工作人都必须与他们所编写技术文档准确性有着直接利害关系。 字串7

  管理人员应该为技术文档编写者设置适当技术准确级别,并要求他们把准确性保持在这一范围之内。由于一些技术文档编写者对于提升自己对于技术理解总是不太积极主动,因此,增加他们责任让他们面对更多压力对项目里每一个人来说都是有处。如果一个技术文档编写者无法达到更高标准,那么你就需要重新审视一下你技术文档编写者是否能够满足你们团队战略要求,是否能够满足客户们需要呢?

  为了帮助技术文档编写者,你需要让他们对于具体技术有着更深层次认识,因此,作为管理者,你应该:

  让技术文档编写者多参加有关产品设计与开发小组会议。

  让技术文档编写者参与到技术要求、功能规范以及设计方案开发工作中去。

  把技术文档编写者包括进开发小组邮件列表中去。

  这技术文档编写周期,把产品在公司内部进行发布。技术文档编写者很容易变得非常封闭,但是如果把产品在内部首先发布一下,那么就能够给开发人员以及项目管理人员提供一种新途径来了解以前可能并不容易了解情况。

  鼓励技术文档编写者更多了解有关产品背后所包含各种技术。举个例子来说,如果你开发基于Java语言应用软件,那么,就应该鼓励技术文档编写者多多了解Java编程语言,并且尽量让他们能够流畅掌握这门编程语言。

  技巧四:设置任务优先次序

  通常情况下,主要开发设计人员脑海中包含着有关整个项目信息,而且,有时候还会同时考虑许多其它项目。即使他或者她日程安排已经非常紧张,但是,他们脑海中产品信息对于确保技术文档编写准确性来说是非常重要。

  当前形势让我们不得不以更少资源完成更多任务,而作为开发设计人员,由于他们工作特殊性,这些人总是处于紧张而繁忙状态下。下面是一些技巧,可以帮助你从这些忙碌开发设计人员哪里获得你所需要信息,并且保证能让他们知识给技术文档编写带来处:

  不要让他们从头至尾审阅技术文档。
  和技术文档编写者一起确定哪些部分必须让开发设计人员进行审阅。

  与他们一起利用大段完整时间来审阅技术文档。

  如果技术文档审阅者时间表安排得很紧,那么就给他提供一个具体列表,在其中明确哪些部分你需要他进行审阅。并且保证让小组内其他成员完成剩余部分审阅工作。技术文档中与审阅者专业技术领域直接相关部分绝对是需要他进行仔细审阅。

  更完成审阅工作

  充分有效完成技术文档审阅工作不仅会让外部用户,也会让内部用户从中受益。但是,经常会有技术人员认为做这样工作是没有多大意义,那么,作为管理者就面对着这样一种挑战,就是要在整个审阅过程中设置优先次序从而保证为开发工作所做出努力获得成功。

       软件测试文档的流程
       整个测试过程的文档。

       先写测试策略,测试策略包括:所要测试的范围,阶段的划分,已经每个阶段完成的标准;

       然后是书写测试计划,测试计划主要包括:谁来做,在哪里做,什么时间做,为什么做,和做什么;

       接着书写测试方案,如果比较简单的就不需要书写测试方案,直接在测试计划里就可以写明白,比较复杂的才写测试方案,测试方案是书写专项测试计划的,以保证专项测试完成;

       再写测试用例,也就是说该怎么做;

       测试执行后生成测试记录和缺陷报告;

       测试结束后,生成测试报告。

文档资料规范要求
一、资料格式要求

1、纸型

      所有纸质文字资料除个别表格必须使用A3纸以外,其余一律用A4复印纸。

2、封面

       文件必须按《国家行政机关公文格式》执行。纸质材料一般不加封面,确需加封面的材料可以加上,如规章制度、材料汇编等。封面可使用必要的文字和徽标,但不宜使用花边和其它图案。加封面的材料同时应加封底。

3、文档

(1)页面设置:

       页面、版式原则上使用软件默认设置,即:上2.54cm,下2.54cm,页眉1.5cm,页脚1.75cm,左右可调整为2.5cm,页码统一在右下角,纵向排列的每页行数控制在44-48行之间,横向排列的每页行数控制在26-29行之间。为避免最后一页只是几行占一页的现象,可适当收缩行距,使文件成为几张整页,但收缩行距不宜小于20磅。

(2)标题

       标题用宋体三号字加粗,顶行。副标题居中排列,使用4号仿宋,但不与正文字体重复,破折号占2格。

(3)正文

用仿宋体四号字

        正文内1级标题文字使用4号仿宋、加粗,2级标题使用楷体(或华文楷体),3级标题使用仿宋体,4级标题使用仿宋体。标题单独成行时,均无需标点。

       不提倡正文内使用加粗或艺术字体,如行书、隶书、魏书、细圆体、综艺体、琥珀体等,以保持公文严肃、文面整洁。

(4)结构层次序数、标点、段落 

       序数:第一层为“一、”,第二层为“(一)”,第三层为“1”,第四层为“(1)”。不使用不规范的序号,如1)、A、a等。

       标点:数字序号后统一用顿号,正文内容如果有需要编码序号时,须采用统一的手动序号编码,切勿一部分自动序号,一部分手动序号,造成排版格式的不一致。

       段落:每自然段文字开头前空2格,第2行起顶格。

(5)数字

       数字除成文日期、部分结构层次序数和在词、词组、惯用语、缩略语、具有修辞色彩语句中作为词素的数字必须使用汉字外,应当使用阿拉伯数字。

4、表格

       资料组统一提供的表格中已设定好的行宽、列高及文字不得任意修改。自制的表格要注意美观、居中,字体参考文档的要求。

5、数据

       凡提供涉及统计数据的资料,必须准确无误,必须保持三年统计口径的一致性。

二、落款、盖印

       所有纸质文字资料必须署上单位名称、日期,加盖公章。落款位置在正文后空2行,单位名称按印章全称。盖印,可不写单位名称。成文日期中“○”用插入符号里的几何图形,或用区位码0180,不能用阿拉伯数“0”。最后一个字离右边沿4格。盖章跨年月日,上2/3,下1/3,左右居中,端正清晰。

三、照片

       4R冲晒(或复印),一张A4纸放两张照片,每张照片需附文字说明,包括时间、地点、人物、事情。电子版的照片,每个活动设一个文件夹,同样要附文字说明。(不要将照片剪辑到Word上)

四、复印

       上下左右居中对齐,如无特殊需要,版面图文的颜色均为黑色,尽量双页印刷,做到均匀清晰,杜绝漏印、倒印等错误现象。重要材料的复印件必须注明“与原件相符”字样,并加盖公章(红色)。

五、装订

        一律用夹子夹在左侧,不需装订。在首页的左上角用铅笔注明资料卷号,如:3-2-17

六、注意事项

        学年和年度的区别,区划调整前后名称的区别,及时间的界定


文档

1. 保持文档整洁,书写工整,使用黑笔填写。

2. 使用订数订装订文档左上角。

3. 文档要分类摆放,site log和site folder分开。

游戏软件文档编写规范

       文档编写标准化:在游戏开发之先,实际上,美术,程序,游戏设计各部门及各部门之后,就已经有这个了,如游戏文件的命名,部门文档或文件的命名,还有一些文档或是表中,或是脚本中的说明书,都是此类 。

       可行性分析报告:这个就是立项报告,游戏软件的可行性分析,一些要对比分析市场同类产品,风险评估等等,在它个规范之外的东西。一般由主设计师及项目负责人来写一些与程序相关,与美术相关,也 峁┫喙氐氖 ?nbsp;

       项目开发计划:这个面向的用户是团队及投资人,要非常清楚的写明各部门在各阶段计划完成什么。由项目负责人及各部门负责来写这个。

       软件需求说明书:这个是由游戏设计部门与程序部门一起完成(但大部分公司游戏设计部门达不到这个水平),也就是游戏的数据结构啊,数据库列啊,等等东西 。

        概要设计说明书:这个就是游戏的总案,用来指导团队开发的总方向,如果有变动,优先会改这个,就是一个游戏开发过程中的路灯,是由主设计师来写这个的。

       详细设计说明书:这个在游戏开发过程中,由N个文档共同构成,但大概规范不必拘泥,视写的文档的类型可自行调整。这是各部门都是如此,都有自己的规范。写这个,一般就是游戏设计师

       用户操作手册:这个对应游戏开发,分两部分:
       对内,在各目录中,各文档都应该有比较清楚的标释或是说明,作用在于如果新同事或是有人接你的工作,至少他应该可以知道怎么继续,程序部门对应的程序文件的注释。
       对外,就是给玩家说明书,官方网站的一些内容,也在此例。
      上面的工作,是由游戏设计部门完成(对内的,只对本部门)

       测试计划:这个是由主设计师来做的,就是在内部内测时时,主要测什么,有多少人来做,如何测法,测试的目的要明确
测试的目的,如同场景用户压力测试,门派平衡测试,模拟升级测试。
       PS:题外一下,如果你们的主程够强,一部分的测试可以虚拟机器完成,曾经的某项目中,在中期门派平衡测试和模拟升级测试,设计部门在没有软件的情况下,用excel都已经做的达到目的了

       测试分析报告 :由各部门主管完成,要总结测试的结果,要修改的地方,如果修改等等,然后安排活大家分头去修改自己负责的地方

       项目开发总结报告:这个,别的公司我不知道,但我每当一阶段都会自己做个总结的,如果是比较正规的公司会要求部门管理人员写这个的

       软件维护手册:这个是交GM部门的,是由游戏设计部门来写的,对应网络游戏是这样的。包括GM的工具的设计,GM的培训计划等等

       软件问题报告 :这个就是对应网络游戏软件,就是玩家反馈BUG或是一些意见的处理行为的文档,由游戏设计部负责来完成,执行人为设计部与GM部门

       软件修改报告:这个不是很需要报告的,但需要游戏设计部负责来安排这个工作,不管是哪的问题进行分流处理。

2007年11月26日 星期一 10:53A、三种编写方法

  1、 用好的结构化和自然语言编写文本型文档;

  2、 建立图形化模型,这些模型可以描绘转换过程、系统状态、和它们之间的变化、数据关系、逻辑流或对象类和他们的关系;

  3、 编写形式化规格说明,这可以通过使用数学上精确的形式化逻辑语言来定义需求。

  多种编写方法可在同一个文档使用,根据需要选择,或互为补充,以能够把需求说明白为目的。

  B、应有成果

   1、 各业务手工办理流程文字说明;

   2、 各业务手工办理流程图;

   3、 各业务手工办理各环节输入输出表单、数据来源;

   4、 目标软件系统功能划分(示意图及文字说明);

   5、 目标软件系统中各业务办理流程文字说明;

   6、 目标软件系统中各业务办理流程图(模型);

   7、 目标软件系统中各业务办理各环节数据、数据采集方式、数据间的内在联系分析。

   8、 目标软件系统用户界面图、各式系统逻辑模型图及说明

  C、文档工具推荐

   1、 调研结果《需求分析说明书》格式参照开发文档模板;

   2、 单位组织结构图、功能模块分解图用VISIO绘制,或直接用WORD中的画图工具;

   3、 业务流程图用VISIO中的FLOWCHART模板绘制;

   4、 系统逻辑模型使用ROSE绘制活用VISIO中的UML模板绘制;

   5、 软件用户界面用VISIO中的WIN95 USER INTERFACE模板绘制;

   6、 数据物理模型用POWERDESINER绘制;

  D、需求文档编写原则

   1、 句子简短完整,具有正确的语法、拼写和标点;

   2、 使用的术语与词汇表中所定义的一致;

   3、 需求陈述应该有一致的样式,例如“系统必须..”或者“用户必须..”,并紧跟一个行为动作和可观察的结果。;

   4、 避免使用模糊、主观的术语,减少不确定性,如“界面友好、操作方便”;

   5、 避免使用比较性词语,如“提高”,应定量说明提高程度

软件工程文档编写标准
       在项目开发过程中,应该按要求编写好十三种文档,文档编制要求具有针对性、精确性、清晰性、完整性、灵活性、可追溯性。
  ◇ 可行性分析报告:说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施方案,说明并论证所选定实施方案的理由。

  ◇ 项目开发计划:为软件项目实施方案制订出具体计划,应该包括各部分工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。

   ◇ 软件需求说明书(软件规格说明书):对所开发软件的功能、性能、用户界面及运行环境等作出详细的说明。它是在用户与开发人员双方对软件需求取得共同理解并达成协议的条件下编写的,也是实施开发工作的基础。该说明书应给出数据逻辑和数据采集的各项要求,为生成和维护系统数据文件做好准备。

  ◇ 概要设计说明书:该说明书是概要实际阶段的工作成果,它应说明功能分配、模块划分、程序的总体结构、输入输出以及接口设计、运行设计、数据结构设计和出错处理设计等,为详细设计提供基础。

  ◇ 详细设计说明书:着重描述每一模块是怎样实现的,包括实现算法、逻辑流程等。

  ◇ 用户操作手册:本手册详细描述软件的功能、性能和用户界面,使用户对如何使用该软件得到具体的了解,为操作人员提供该软件各种运行情况的有关知识,特别是操作方法的具体细节。

  ◇ 测试计划:为做好集成测试和验收测试,需为如何组织测试制订实施计划。计划应包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。

  ◇ 测试分析报告:测试工作完成以后,应提交测试计划执行情况的说明,对测试结果加以分析,并提出测试的结论意见。

  ◇ 开发进度月报:该月报系软件人员按月向管理部门提交的项目进展情况报告,报告应包括进度计划与实际执行情况的比较、阶段成果、遇到的问题和解决的办法以及下个月的打算等。

  ◇ 项目开发总结报告:软件项目开发完成以后,应与项目实施计划对照,总结实际执行的情况,如进度、成果、资源利用、成本和投入的人力,此外,还需对开发工作做出评价,总结出经验和教训。

  ◇ 软件维护手册:主要包括软件系统说明、程序模块说明、操作环境、支持软件的说明、维护过程的说明,便于软件的维护。

  ◇ 软件问题报告:指出软件问题的登记情况,如日期、发现人、状态、问题所属模块等,为软件修改提供准备文档。

  ◇ 软件修改报告:软件产品投入运行以后,发现了需对其进行修正、更改等问题,应将存在的问题、修改的考虑以及修改的影响作出详细的描述,提交审批。

项目开发计划
1 引言
1.1 编写目的:阐明编写可行性研究报告的目的,提出读者对象

1.2 项目背景:应包括
  ● 项目的委托单位、开发单位和主管部门;
  ● 该软件系统与其他系统的关系。

1.3 定义:列出文档中用到的专门术语的定义和缩写词的原文

1.4 参考资料:可包括:
  ● 项目经核准的计划任务书、合同或上级机关的批文
  ● 文档所引用的资料、规范等
  ● 列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源;

2 项目概述
2.1 工作内容:简要说明项目的各项主要工作,介绍所开发软件的功能、性能等;若不编写可行性研究报告;则应在本节给出较详细的介绍;

2.2 条件与限制: 阐明为完成项目应具备的条件、开发单位已具备的条件以及尚需创造的条件。必要时还应说明用户及分合同承担的工作、完成期限及其他条件与限制。

2.3 产品

2.3.1程序:列出应交付的程序名称、使用的语言及存储形式。

2.3.2文档:列出应交付的文档。

2.4 运行环境:应包括硬件环境、软件环境。

2.5 服务:阐明开发单位可向用户提供的服务。如人员培训、安装、保修、维护和其他运行支持。

2.6 验收标准

3 实施计划
3.1 任务分解:任务的划分及各项任务的负责人。

3.2 进度:按阶段完成的项目,用图表说明开始时间、完成时间。

3.3 预算

3.4 关键问题:说明可能影响项目的关键问题,如设备条件、技术难点或其他风险因素,并说明对策。

4 人员组织及分工
5 交付期限
6 专题计划要点
  如测试计划、质量保证计划、配置管理计划、人员培训计划、系统安装计划等。

软件需求说明书
1 引言
1.1 编写目的:阐明编写需求说明书的目的,指明读者对象。

1.2 项目背景:应包括
  ● 项目的委托单位、开心单位和主管部门;
  ● 该软件系统与其他系统的关系。

1.3 定义:列出文档中所用到的专门术语的定义和缩写词的愿文。

1.4 参考资料:可包括
  ● 项目经核准的计划任务书、合同或上级机关的批文
  ● 文档所引用的资料、规范等
  ● 列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源

2 任务概述
2.1 目标

2.2 运行环境

2.3 条件与限制

3 数据描述
3.1 表态数据

3.2 动态数据:包括输入数据和输出数据。

3.3 数据库描述:给出使用数据库的名称和类型。

3.4 数据词典

3.5 数据采集

4 功能需求
4.1功能划分

4.2功能描述

5 性能需求
5.1 数据精确度

5.2 时间特性:如响应时间、更新处理时间、数据转换与传输时间、运行时间等。

5.3 适应性:在操作方式、运行环境、与其他软件的接口以及开发计划等发生变化时,应具有的适应能力。

6 运行需求
6.1 用户界面:如屏幕格式、报表格式、菜单格式、输入输出时间等。

6.2 硬件接口

6.3 软件接口

6.4 故障处理

7 其他需求
  如可使用性、安全保密、可维护性、可移植性等。

概要设计说明书
1 引言
1.1 写目的:阐明编写概要设计说明书的目的,指明读者对象。

1.2 项目背景:应包括
  ● 项目的委托单位、开发单位和主管部门
  ● 该软件系统与其他系统的关系。

1.3 定义:列出本文档中所用到的专门术语的定义和缩写词的愿意。

1.4 参考资料:
  ● 列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源
  ●项目经核准的计划任务书、合同或上级机关的批文;项目开发计划;需求规格说明书;测试计划(初稿);用户操作手册
  ● 文档所引用的资料、采用的标准或规范。

2 任务概述
2.1 目标

2.2 需求概述

2.3 条件与限制

3 总体设计
3.2 总体结构和模块外部设计

3.3 功能分配:表明各项功能与程序结构的关系。

4 接口设计
4.1 外部接口:包括用户界面、软件接口与硬件接口。

4.2 内部接口:模块之间的接口。

5 数据结构设计
6 逻辑结构设计
  所有文档的统一封面格式如下页所示。

7 物理结构设计
8 数据结构与程序的关系
9 运行设计
9.1 运行模块的组合

9.2 运行控制

9.3 运行时间

10 出错处理设计
10.1 出错输出信息

10.2 出错处理对策:如设置后备、性能降级、恢复及再启动等。

11 安全保密设计
12 维护设计
  说明为方便维护工作的设施,如维护模块等。

详细设计说明书
1 引言
1.1 编写目的:阐明编写详细设计说明书的目的,指明读者对象。

1.2 项目背景:应包括项目的来源和主管部门等。

1.3 定义:列出本文档中所用到的专门术语的定义和缩写词的愿意。

1.4 参考资料:
  ● 列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源
  ●项目经核准的计划任务书、合同或上级机关的批文;项目开发计划;需求规格说明书;概要设计说明书;测试计划(初稿);用户操作手册
  ● 文档所引用的资料、软件开发的标准或规范。

2 总体设计
2.1 需求概述

2.2 软件结构:如给出软件系统的结构图。

3 程序描述
3.1 逐个模块给出以下说明:
  ● 功能
  ● 性能
  ● 输入项目
  ● 输出项目

3.2 算法:模块所选用的算法。

3.3 程序逻辑:详细描述模块实现的算法,可采用:标准流程图;PDL语言;N-S图;判定表等描述算法的图表。

3.4 接口
  ● 存储分配
  ● 限制条件

3.5测试要点:给出测试模块的主要测试要求。

用户操作手册
1 引言
1.1 编写目的:阐明编写手册的目的,指明读者对象。

1.2 项目背景:说明项目的来源、委托单位、开发单位及和主管部门。

1.3 定义:列出手册中使用的专门术语的定义和缩写词的愿意。

1.4 参考资料:
  ● 列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源
  ● 项目经核准的计划任务书、合同或上级机关的批文;项目开发计划;需求规格说明书;概要设计说明书;详细设计说明书;测试计划
  ● 文档中所引用的其他资料、采用的软件工程标准或软件工程规范。

2 软件概述
2.1 目标

2.2 功能

2.3 性能

2.4 数据精确度:包括输入、输出及处理数据的精度。

2.5 时间特性:如响应时间、处理时间、数据传输时间等。

2.6 灵活性:在操作方式、运行环境需做某些变更时软件的适应能力。

3 运行环境
3.1 硬件
  ● 列出软件系统运行时所需的硬件最小配置,如计算机型号、主存容量
  ● 外存储器、媒体、记录格式、设备型号及数量
  ● 输入、输出设备
  ● 数据传输设备及数据转换设备的型号及数量。

3.2 支持软件
  ● 操作系统名称及版本号
  ● 语言编译系统或汇编系统的名称及版本号
  ● 数据库管理系统的名称及版本号
  ● 其他必要的支持软件

4 使用说明
4.1 安装和初始化:给出程序的存储形式、操作命令、反馈信息及其做含意、表明安装完成的测试实例以及安装所需的软件工具等。

4.2 输入:给出输入数据或参数的要求。
  ● 数据背景:说明数据来源、存储媒体、出现频度、限制和质量管理等。
  ● 数据格式:如长度、格式基准、标号、顺序、分隔符、词汇表、省略和重复、控制。
  ● 输入举例。

4.3 输出:给出每项输出数据的说明。
  ● 数据背景:说明输出数据的去向、使用频度、存放媒体及质量管理等。
  ● 数据格式:详细阐明每一输出数据的格式,如首部、主体和尾部的具体形式。
  ● 举例

4.4 出错和恢复:给出出错信息及其含意;用户应采取的措施,如修改、恢复、再启动。

4.5 查询:说明如何操作。

5 运行说明
5.1 运行表:列出每种可能的运行情况,说明其运行目的。

5.2 运行步骤:按顺序说明每和运行的步骤,应包括:

5.3 运行控制

5.4 操作信息:运行目的、运行目的、操作要求、启动方法、预计运行时间、操作命令格式及说明、其他事项;

5.5输入/输出文件:给出建立或更新文件的有关信息,如:文件的名称及编号;记录媒体;存留的目录;文件的支配:说明确定保留文件或废弃文件的准则,分发文件的对象,战胜硬件的优先级及保密控制等。

5.6 启动或恢复过程

6 非常规过程
  提供应急戒非常规操作的必要信息及操作步骤,如出错处理操作、向后备系统切换操作及维护人员须知的操作和注意事项。

7 操作命令一览表
  按字母顺序逐个列出全部操作命令的格式、功能及参数说明。

8 程序文件(或命令文件)和数据文件一览表
  按文件名字母顺序或按功能与模块分类顺序逐个列出文件名称、标识符及说明。

9 用户操作举例

测试计划
1 引言
1.1 编写目的:阐明编写测试计划的目的并指明读者对象。

1.2 项目背景:说明项目的来源、委托单位及主管部门。

1.3 定义:列出测试计划中所用到的专门术语的定义和缩写词的原意。

1.4参考资料:列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源,可包括:项目的计划任务书、合同或批文;项目开发计划;需求规格说明书;概要设计说明书;详细设计说明书;用户操作手册;本测试计划中引用的其他资料、采用
的软件开发标准或规范。

2 任务概述
2.1 目标

2.2 运行环境

2.3 需求概述

2.4 条件与限制

3 计划
3.1 测试方案:说明测试方法和选取测试用例的原则。

3.2 测试项目:列出组装测试和确认测试中每一项测试的内容、名称、目的和进度。

3.3 测试准备

3.4 测试机构及人员:测试机构名称、负责人和职责。

4 测试项目说明
4.1 按顺序逐个对测试项目做出说明

4.1.1 测试项目名称及测试内容

4.1.2 测试用例

4.1.3 输入:输入的数据和输入命令。

4.1.4 输出:预期的输出数据。

4.2 步骤及操作

4.3 允许偏差:给出实测结果与预期结果之间允许偏差的范围。

4.4 进度

4.5 条件:给出项测试对资源的特殊要求,如设备、软件、人员等。

4.6 测试资料:说明项测试所需的资料。

5 评价
5.1 范围:说明所完成的各项测试说明问题的范围及其局限性。

5.2 准则:说明评论测试结果的准则。

测试分析报告
1 引言
1.1 编写目的:阐明编写测试分析报告的目的并指明读者对象。

1.2 项目背景:说明项目的来源、委托单位及主管部门。

1.3定义:列出测试分析报告中所用到的专门术语的定义和缩写词的原意。

1.4参考资料:列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源,可包括:项目的计划任务书、合同或批文;项目开发计划;需求规格说明书;概要设计说明书;详细设计说明书;用户操作手册;测试计划;测试分析报告所引用的其他资料、采用的软件工程标准或工程规范。

2 测试计划招待情况
2.1 机构和人员:给出测试机构名称、负责人和参与测试人员名单。

2.2 测试结果:按顺序给出每一测试项目的:实测结果数据;与预期结果数据的偏差;该项测试表明的事实;该项测试发现的问题。

3 软件需求测试结论
  按顺序给出每一项需求测试的结论。包括:证实的软件能力;局限性(即项需求未得到充分测试的情况及原因。

4 评价
4.1 软件能力:经过测试所表明的软件能力。

4.2 缺陷和限制:说明测试所揭露的软件缺陷和不足,以及可能给软件运行带来的影响。

4.3 建议:提出为弥补上述缺陷的建议。

4.4 测试结论:说明能否通过。

开发进度月报
1 报告时间及所处的开发阶段
2 工程进度
2.1 本月内的主要活动

2.2 实际进展与计划比较

3 所用工时
  按不同层次人员分别计时。

        在项目开发过程中,应该按要求编写好十三种文档,文档编制要求具有针对性、精确性、清晰性、完整性、灵活性、可追溯性。

  ◇ 可行性分析报告:说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施方案,说明并论证所选定实施方案的理由。
  ◇ 项目开发计划:为软件项目实施方案制订出具体计划,应该包括各部分工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。
  ◇ 软件需求说明书(软件规格说明书):对所开发软件的功能、性能、用户界面及运行环境等作出详细的说明。它是在用户与开发人员双方对软件需求取得共同理解并达成协议的条件下编写的,也是实施开发工作的基础。该说明书应给出数据逻辑和数据采集的各项要求,为生成和维护系统数据文件做好准备。
  ◇ 概要设计说明书:该说明书是概要实际阶段的工作成果,它应说明功能分配、模块划分、程序的总体结构、输入输出以及接口设计、运行设计、数据结构设计和出错处理设计等,为详细设计提供基础。
  ◇ 详细设计说明书:着重描述每一模块是怎样实现的,包括实现算法、逻辑流程等。
  ◇ 用户操作手册:本手册详细描述软件的功能、性能和用户界面,使用户对如何使用该软件得到具体的了解,为操作人员提供该软件各种运行情况的有关知识,特别是操作方法的具体细节。
  ◇ 测试计划:为做好集成测试和验收测试,需为如何组织测试制订实施计划。计划应包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。
  ◇ 测试分析报告:测试工作完成以后,应提交测试计划执行情况的说明,对测试结果加以分析,并提出测试的结论意见。
  ◇ 开发进度月报:该月报系软件人员按月向管理部门提交的项目进展情况报告,报告应包括进度计划与实际执行情况的比较、阶段成果、遇到的问题和解决的办法以及下个月的打算等。
  ◇ 项目开发总结报告:软件项目开发完成以后,应与项目实施计划对照,总结实际执行的情况,如进度、成果、资源利用、成本和投入的人力,此外,还需对开发工作做出评价,总结出经验和教训。
  ◇ 软件维护手册:主要包括软件系统说明、程序模块说明、操作环境、支持软件的说明、维护过程的说明,便于软件的维护。
  ◇ 软件问题报告:指出软件问题的登记情况,如日期、发现人、状态、问题所属模块等,为软件修改提供准备文档。
  ◇ 软件修改报告:软件产品投入运行以后,发现了需对其进行修正、更改等问题,应将存在的问题、修改的考虑以及修改的影响作出详细的描述,提交审批。

可行性分析报告

1 引言
1.1 编写目的:阐明编写可行性研究报告的目的,提出读者对象。
1.2 项目背景:应包括
  ● 所建议开发软件的名称
  ● 项目的任务提出者、开发者、用户及实现软件的单位
  ● 项目与其他软件或其他系统的关系。
1.3 定义:列出文档中用到的专门术语的定义和缩写词的原文。
1.4 参考资料:列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源,可包括
  ● 项目经核准的计划任务书、合同或上级机关的批文
  ● 与项目有关的已发表的资料
  ● 文档中所引用的资料,所采用的软件标准或规范
2 可行性研究的前提
2.1 要求:列出并说明建议开发软件的的基本要求,如
  ● 功能
  ● 性能
  ● 输入/输出
  ● 基本的数据流程和处理流程
  ● 安全与保密要求
  ● 与软件相关的其他系统
  ● 完成日期
2.2 目标:可包括
  ● 人力与设备费用的节省
  ● 处理速度的提高
  ● 控制精度或生产力的提高
  ● 管理信息服务的改进
  ● 决策系统的改进
  ● 人员工作效率的提高
2.3 条件、假定和限制:可包括
  ● 建议开发软件运行的最短寿命
  ● 进行显然方案选择比较的期限
  ● 经费来源和使用限制
  ● 法律和政策方面的限制
  ● 硬件、软件、运行环境和开发环境的条件和限制
  ● 可利用的信息和资源
  ● 建议开发软件投入使用的最迟时间
2.4 可行性研究方法
2.5 决定可行性的主要因素
3 对现有系统的分析
3.1 处理流程和数据流程
3.2 工作负荷
3.3 费用支出:如人力、设备、空间、支持性服务、材料等项开支
3.4 人员:列出所需人员的专业技术类别和数量
3.5 设备
3.6 局限性:说明现有系统存在的问题以及为什么需要开发新的系统
4 所建议技术可行性分析
4.1 对系统的简要描述
4.2 与现有系统比较的优越性
4.3 处理流程和数据流程
4.4 采用建议系统可能带来的影响
  ● 对设备的影响
  ● 对现有软件的影响
  ● 对用户的影响
  ● 对系统运行的影响
  ● 对开发环境的影响
  ● 对经费支出的影响
4.5 技术可行性评价:包括
  ● 在限制条件下,功能目的是否达到
  ● 利用现有技术,功能目的是否达到
  ● 对开发人员数量和质量的要求,并说明能否满足
  ● 在规定的期限内,开发能否完成
5 所建议系统经济可行性分析
5.1 支出
5.2 效益
5.3 收益/投资比
5.4 投资回收周期
5.5 敏感性分析:指一些关键性因素,如:
  ● 系统生存周期长短
  ● 系统工作负荷量
  ● 处理速度要求
  ● 设备和软件配置变化对支出和效益的影响等的分析
6 社会因素可行性分析
6.1 法律因素:如
  ● 合同责任
  ● 侵犯专利权
  ● 侵犯版权
6.2 用户使用可行性:如
  ● 用户单位的行政管理
  ● 工作制度
  ● 人员素质等能否满足要求
7 其他可供选择的方案
  逐个阐明其它可供选择的方案,并重点说明未被推荐的理由。
8 结论意见
  ● 可着手组织开发
  ● 需等待若干条件具备后才能开发
  ● 需对开发目标进行某些修改
  ● 不能进行或不必进行
  ● 其它

项目开发计划

1 引言
1.1 编写目的:阐明编写可行性研究报告的目的,提出读者对象
1.2 项目背景:应包括
  ● 项目的委托单位、开发单位和主管部门;
  ● 该软件系统与其他系统的关系。
1.3 定义:列出文档中用到的专门术语的定义和缩写词的原文
1.4 参考资料:可包括:
  ● 项目经核准的计划任务书、合同或上级机关的批文
  ● 文档所引用的资料、规范等
  ● 列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源;
2 项目概述
2.1 工作内容:简要说明项目的各项主要工作,介绍所开发软件的功能、性能等;若不编写可行性研究报告;则应在本节给出较详细的介绍;
2.2 条件与限制: 阐明为完成项目应具备的条件、开发单位已具备的条件以及尚需创造的条件。必要时还应说明用户及分合同承担的工作、完成期限及其他条件与限制。
2.3 产品
2.3.1程序:列出应交付的程序名称、使用的语言及存储形式。
2.3.2文档:列出应交付的文档。
2.4 运行环境:应包括硬件环境、软件环境。
2.5 服务:阐明开发单位可向用户提供的服务。如人员培训、安装、保修、维护和其他运行支持。
2.6 验收标准
3 实施计划
3.1 任务分解:任务的划分及各项任务的负责人。
3.2 进度:按阶段完成的项目,用图表说明开始时间、完成时间。
3.3 预算
3.4 关键问题:说明可能影响项目的关键问题,如设备条件、技术难点或其他风险因素,并说明对策。
4 人员组织及分工
5 交付期限
6 专题计划要点
  如测试计划、质量保证计划、配置管理计划、人员培训计划、系统安装计划等。

6.1 变量使用
1、不允许随意定义全局变量。
2、一个变量只能有一个用途;变量的用途必须和变量的名称保持一致。
3、所有变量都必须在类和函数最前面定义,并分类排列。

6.2 数据库操作
1、查找数据库表或视图时,只能取出确实需要的那些字段。
2、使用无关联子查询,而不要使用关联子查询。
3、清楚明白地使用列名,而不能使用列的序号。
4、ASP操作时只在必要时创建RecordSet对象

6.3 对象使用
尽可能晚地创建对象,并且尽可能早地释放它。

6.4 模块设计原则
1、不允许随意定义公用的函数和类。
2、函数功能单一,不允许一个函数实现两个及两个以上的功能。
3、不能在函数内部使用全局变量,如要使用全局变量,应转化为局部变量。
4、函数与函数之间只允许存在包含关系,而不允许存在交叉关系。即两者之间只存在单方向的调用与被调用,不存在双向的调用与被调用。

结构化要求
1、用 IF 语句来强调只执行两组语句中的一组。禁止 ELSE GOTO 和 ELSE RETURN。
2、用 CASE 实现多路分支而不是多个IF
3、避免从循环引出多个出口。
4、函数只有一个出口。
5、不使用条件赋值语句。
6、避免不必要的分支。
7、不要轻易用条件分支去替换逻辑表达式

6.6 函数返回值原则
1、避免使用结构体等复杂类型
2、使用逻辑类型:该函数只需要获得成功或者失败的返回信息时候
3、使用int 类型:错误代码用负数表示,成功返回0

七、数据库命名规范:
1、表命名:用一个或三个以下英文单词组成,单词首字母大写,如:DepartmentUsers;
2、表主键名称为:表名+ID,如Document表的主键名为:DocumentID
3、存储过程命名:表名+方法,如:p_my_NewsAdd,p_my_NewsUpdate;
4、视图命名:View_表名,如:ViewNews;
5、Status为表中状态的列名,默认值为0,在表中删除操作将会改变Status的值而不真实删除该记录;
6、Checkintime为记录添加时间列,默认值为系统时间;
7、表、存储过程、视图等对象的所有都为dbo,不要使用数据库用户名,这样会影响数据库用户的更改。

八、注释规范
8.1 概述
1、注释要求英文及英文的标点符号。
2、注释中,应标明对象的完整的名称及其用途,但应避免对代码过于详细的描述。
3、每行注释的最大长度为100个字符。
4、将注释与注释分隔符用一个空格分开。
5、不允许给注释加外框。
6、编码的同时书写注释。
7、重要变量必须有注释。
8、变量注释和变量在同一行,所有注释必须对齐,与变量分开至少四个“空格”键。例:
int   m_iLevel,m_iCount;      // m_iLevel ....tree level
                             // m_iCount ....count of tree items
string m_strSql;             //SQL
9、典型算法必须有注释。
10、在循环和逻辑分支地方的上行必须就近书写注释。
11、程序段或语句的注释在程序段或语句的上一行
12、在代码交付之前,必须删掉临时的或无关的注释。
13、最终发布时,可以依需要删除部分注释。

8.2 自建代码文件注释
对于自己创建的代码文件(如函数、脚本),在文件开头,一般编写如下注释(VBS则第行加')(可采用中文):

/******************************************************
FileName:文件名
Edits the Tool:编辑工具
Copyright   2006-2007 开发组名称
Writer:作者名
Create Date:按月日年格式书写,月份及日不足10前面补0,例:06/01/2006
Rewriter:修改者名
Rewrite Date:修改日期
Main Content(Function Name、parameters、returns)主要内容及作用,只简单写,单独过程及函数前再加相应注释
******************************************************/

8.3 方法-过程|函数及相关注释
一般加如下注释(可采用中文)
/******************************************************
Depiction:本方法-过程|函数说明
Param:参数说明
Returns:返回值说明
Writer:编写者
Create Date:时间
******************************************************/


附:数据类型缩写
整数型 int
长整型 lng
字符型 str
布尔型 boo
单精度 sng
双精度 dub
字节型 bit
日期型 dat
货币型 cur
对象型 obj
自定型 udt
数组    arr
错误    err

别在程序中使用固定数值,用常量代替。
别用字符串常数。用资源文件。
避免使用很多成员变量。声明局部变量,并传递给方法。不要在方法间共享成员变量。如果在几个方法间共享一个成员变量,那就很难知道是哪个方法在什么时候修改了它的值。
必要时使用enum 。别用数字或字符串来指示离散值。


别把成员变量声明为 public 或 protected。都声明为 private 而使用 public/protected 的Properties.
不在代码中使用具体的路径和驱动器名。 使用相对路径,并使路径可编程。
永远别设想你的代码是在“C:”盘运行。你不会知道,一些用户在网络或“Z:”盘运行程序。
应用程序启动时作些“自检”并确保所需文件和附件在指定的位置。必要时检查数据库连接。出现任何问题给用户一个友好的提示。
如果需要的配置文件找不到,应用程序需能自己创建使用默认值的一份。
如果在配置文件中发现错误值,应用程序要抛出错误,给出提示消息告诉用户正确值。

错误消息需能帮助用户解决问题。永远别用象"应用程序出错", "发现一个错误" 等错误消息。而应给出象 "更新数据库失败。请确保登陆id和密码正确。" 的具体消息。  
显示错误消息时,除了说哪里错了,还应提示用户如何解决问题。不要用 象 "更新数据库失败。"这样的,要提示用户怎么做:"更新数据库失败。请确保登陆id和密码正确。"
显示给用户的消息要简短而友好。但要把所有可能的信息都记录下来,以助诊断问题。
注释
别每行代码,每个声明的变量都做注释。
在需要的地方注释。可读性强的代码需要很少的注释。如果所有的变量和方法的命名都很有意义,会使代码可读性很强并无需太多注释。
行数不多的注释会使代码看起来优雅。但如果代码不清晰,可读性差,那就糟糕。
如果应为某种原因使用了复杂艰涩的原理,为程序配备良好的文档和重分的注释。
对一个数值变量采用不是0,-1等的数值初始化,给出选择该值的理由。
简言之,要写清晰,可读的代码以致无须什么注释就能理解。
对注释做拼写检查,保证语法和标点符号的正确使用。

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页