软 件 开 发 流 程 规 范 V1。0
德联软件有限责任公司
编制人： 侯秀美 审核人： 2015 年 8 月 19 日
目录
目录 .................................................................................................................................................. 0 一、概述........................................................................................................................................... 2 二、开发流程规范 ........................................................................................................................... 3
2.1 系统软硬件开发环境 ........................................................................................................ 3 2。2 系统架构（系统组成) ................................................................................................... 5 2.3 系统功能模块设计 ............................................................................................................ 6 2.4 系统功能开发流程图 ........................................................................................................ 6 2.5 开发修改记录 .................................................................................................................... 7 三、开发代码规范 ........................................................................................................................... 8
3。1 文件结构 ......................................................................................................................... 8
3。1.1 文件信息声明 ...................................................................................................... 8 3.1.2 头文件的结构 ....................................................................................................... 10 3。1.3 定义文件的结构 ................................................................................................ 11 3。1。4 头文件的作用 ................................................................................................. 12 3。1.5 目录结构 ............................................................................................................ 13 3。2 命名规则 ....................................................................................................................... 13
3.2。1 共性原则 ............................................................................................................ 13 3.2。2 Windows变量命名规则 .................................................................................... 14 3.3 程序风格.......................................................................................................................... 17
3。3.1 空行 .................................................................................................................... 17 3.3。2 代码行 ................................................................................................................ 18 3.3。3 代码行内的空格 ................................................................................................ 19 3。3.4 对齐 .................................................................................................................... 20 3。3。5 长行拆分 ......................................................................................................... 22 3。3。6 修饰符的位置 ................................................................................................. 23 3.3.7 注释....................................................................................................................... 23 3。4 函数设计 ....................................................................................................................... 26
3.4.1 参数的规则 ........................................................................................................... 26 3。4。2 返回值的规则 ................................................................................................. 27 3。4。3 函数内部实现的规则 ..................................................................................... 30 3。4.4 其它建议 ............................................................................................................ 32 3.4.5 使用断言 ............................................................................................................... 32 3.4。6 引用与指针的比较 ............................................................................................ 33 3。5 变量类型定义 ............................................................................................................... 35 四、软件测试规范 ......................................................................................................................... 36
4.1 单元测试.......................................................................................................................... 36 4。2 系统测试 ....................................................................................................................... 37 4.6 业务测试.......................................................................................................................... 38 4。7 验收测试 ....................................................................................................................... 38
4.8 用户现场测试 .................................................................................................................. 38 五、软件版本管理 ......................................................................................................................... 39
4.1版本管理的必要性 ........................................................................................................... 39
一、概述
本文制定烟台开发区德联软件有限责任公司计算机软件开发规范文档。本规范的目的是使公司软件开发项目阶段清晰、要求明确、任务具体、编写的代码规范，使之规范化、系统化和工程化,向公司内从事软件开发的工程师和管理人员提出一系列规范和要求，从而有利于开发过程的控制和管理，提高所开发软件系统的质量,缩短开发时间,减少开发和维护费用,以保证项目高质量、顺利进行。
本规范包含：开发流程规范和开发代码规范等，开发流程规范需要技术开发人员编写相关内容，希望每个技术人员形成习惯，如有新的内容更新会及时通知大家，如有好的规范要求也可通知编制人员及时更新。
本规范为烟台开发区德联软件有限责任公司内部材料，严禁其他商业应用。
1
二、开发流程规范
接受开发任务，详细阅读软件技术规范或技术文档,如对技术文档有疑义或者不清楚的地方及时与项目总工或用户沟通，根据文档和沟通内容编写项目开发计划,必须包括但不限于系统软硬件开发环境、系统架构、系统功能模块设计、系统功能开发流程图、开发修改记录。
2.1 系统软硬件开发环境
开发环境的搭建,最好形成文档，便于以后同样工作的使用。开发人员要明确系统开发拟采用的数据库、操作系统、开发语言、开发工具、服务器等（具体到版本）。明确整个系统开发工作流程，至少应该包括以下流程。
3
项目启动获取用户需求用户需求文档需求分析项目前期系统结构建立功能模块设计需要变更编码实现系统实现是否需要变更无需变更技术调试未通过系统调试测试未通过集成调试通过试用上线验收项目后期结束 4
2。2 系统架构（系统组成）
确定系统整体体系架构，各层次之间的数据流的连接，确定软件服务器的硬件配置及用户硬件资源配置， 确定与用户软件平台的统一协调。 开发人员在绘制架构图时给出基本框架，能反映出基本意义即可，可以直接用文字代替例子中的图片。
图1 系统逻辑架构图举例
5
图2 物理架构图举例
2.3 系统功能模块设计
给出系统的主要功能模块，每个模块所包含的功能。
图3 图书管理系统模块规划图举例
2.4 系统功能开发流程图
给出系统主要功能的业务流程图.
6
图4 系统功能业务流程图举例
2.5 开发修改记录
1. 开发代码做好备份（可以在完成一个重大功能之后，或者按时间周期性进行备份），以免由于不可抗力导致代码不可修复。
2.在每次重大修改之后要做好记录（改动的具体细节)，修改前的版本要及时备份，可以方面随时还原系统. 修改日期 修改内容 是否备份 备注 7
三、开发代码规范
在研究项目团队协作开发的情况下(这里的团队协作也适合于应用项目的开发），编程时应该强调的一个重要方面是程序的易读性,在保证软件速度等性能指标能满足用户需求的情况下，能让其他程序员容易读懂你所编写的程序。若研究项目小组的所有开发人员都遵循统一的、鲜明的一套编程风格，可以让协作者、后继者和自己一目了然，在很短的时间内看清楚程序结构,理解设计的思路，大大提高代码的可读性、可重用性、程序健壮性、可移植性、可维护性。
制定本编程规范的目的是为了提高软件开发效率及所开发软件的可维护性,提高软件的质量。本规范由程序风格、命名规范、注释规范、程序健壮性、可移植性、错误处理以及软件的模块化规范等部分组成。
此规范以C/C++程序设计讨论。
3.1 文件结构
每个C++/C程序通常分为两个文件。一个文件用于保存程序的声明（declaration），称为头文件。另一个文件用于保存程序的实现（implementation）,称为定义(definition）文件。 C++/C程序的头文件以“。h”为后缀，C程序的定义文件以“。c”为后缀，C++程序的定义文件通常以“。cpp\"为后缀(也有一些系统以“。cc”或“.cxx”为后缀）。
3。1.1 文件信息声明
文件信息声明位于头文件和定义文件的开头（参见示例3-1），主要内容有: （1） 版权信息；
(2） 文件名称，项目代码，摘要，参考文献; （3） 当前版本号，作者/修改者,完成日期； （4） 版本历史信息； （5） 主要函数描述。
//////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// // Copyright (c) 2015， DeLianSoftCompany YanTai 8
// All rights reserved。 // // Filename :filename.h // Project Code ：The project code about this file // Abstract ：Describe the content of this file summarily // Reference :...。。. // // Version ：1.1 // Author :the name of author(mender） // Accomplished date ： September 2， 2004 // // Replaced version ： 1.0 // Original Author ： the name of original author（mender） // Accomplished date ： September 10， 2003 // // Main functions ： // Function 1 Return code Function name（Parameter Explain) // Function 2 Return code Function name（Parameter Explain） // ... // Function n Return code Function name（Parameter Explain) //////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// 示例3-1 文件信息声明
9
☆ 【规则3.1-1】
文件信息声明以两行斜杠开始，以两行斜杠结束，每一行都以两个斜杠开始；
☆ 【规则3.1—2】 文件信息声明包含五个部分，各部分之间以一空行间隔；
☆ 【规则3.1-3】
在主要函数部分描述了文件所包含的主要函数的声明信息，如果是头文件,这一部分是可以省略的。
3.1.2 头文件的结构
头文件由三部分内容组成：
(1) 头文件开头处的文件信息声明（参见示例3—1); (2) 预处理块；
（3） 函数和类结构声明等。
假设头文件名称为 filesystem.h，头文件的结构参见示例3—2. ☆ 【规则3.2-1】
为了防止头文件被重复引用，应当用ifndef/define/endif结构产生预处理块;“#ifndef”或者“#define”后以TAB键代替SPACE键做空格；如果头文件名称是由多个单词组成,则各单词间以下划线“_”连接，例如有头文件名称为“filesystem。h”,则定义如下：“＃ifndef _FILE_SYSTEM_H_”;
☆ 【规则3。2-2】 用 #include< filename。h〉 格式来引用标准库的头文件（编译器将
从标准库目录开始搜索)； ☆ 【规则3。2-3】 用 ＃include “filename.h” 格式来引用非标准库的头文件(编译器将
从用户的工作目录开始搜索)； ☆ 【建议3。2—1】 头文件中只存放“声明”而不存放“定义\";
☆ 【建议3。2-1】 头文件中应包含所有定义文件所定义的函数声明,如果一个头文件对
应多个定义文件,则不同定义文件内实现的函数要分开声明,并作注释以解释所声明的函数从属于那一个定义文件; ☆ 【建议3。2-3】 宏定义和函数声明分离,在两个头文件中定义，如果没有类成员函数，
可以将类和结构的定义与函数声明分离，也就是说一个头文件专用于宏定义，一个头文件专用于类和结构的定义,一个头文件专用于函数声明； ☆ 【建议3。2—4】 在C++ 语法中，类的成员函数可以在声明的同时被定义，并且自动
成为内联函数。这虽然会带来书写上的方便，但却造成了风格不一
10
致，弊大于利。建议将成员函数的定义与声明分开,不论该函数体有多么小。
头文件的结构如下：
//文件信息声明见示例3—1，此处省略。 ＃ifndef _FILE_SYSTEM_H_ //avoid referencing the file filesystem.h repeat #define _FILE_SYSTEM_H_ #include //reference standard head file //global function declare //class structure decalre 3.1。3 定义文件的结构 定义文件有三部分内容： (1） 定义文件开头处的文件信息声明（参见示例3-1）； （2） 对一些头文件的引用； 11 (3) 程序的实现体（包括数据和代码）。 假设定义文件的名称为 filesystem.c，定义文件的结构参见示例3—3。 //文件信息声明见示例3—1，此处省略。 #include “filesystem.h” //reference a head file … //global function realization void Function1(…） { … } //class member function realization void CBox：:Draw(…） ｛ … ｝ 示例3—3 C++/C定义文件的结构 3.1。4 头文件的作用 早期的编程语言如Basic、Fortran没有头文件的概念，C++/C语言的初学者虽然会用使用头文件，但常常不明其理。这里对头文件的作用略作解释： (1） 通过头文件来调用库功能。在很多场合，源代码不便(或不准）向用户公布，只要向用户提供头文件和二进制的库即可。用户只需要按照头文件中的接口声明来调用库功能，而不必关心接口怎么实现的.编译器会从库中提取相应的代码； （2） 头文件能加强类型安全检查。如果某个接口被实现或被使用时，其方式与头文件 12 中的声明不一致，编译器就会指出错误，这一简单的规则能大大减轻程序员调试、改错的负担。 3.1。5 目录结构 如果一个软件的头文件数目比较多（如超过十个），通常应将头文件和定义文件分别保存于不同的目录,以便于维护。 例如可将头文件保存于include目录，将定义文件保存于source目录（可以是多级目录）. 如果某些头文件是私有的，它不会被用户的程序直接引用,则没有必要公开其“声明\".为了加强信息隐藏，这些私有的头文件可以和定义文件存放于同一个目录。 3。2 命名规则 比较著名的命名规则当推“匈牙利” 命名法，该命名规则的主要思想是“在变量和函数名中加入前缀以增进人们对程序的理解”。例如所有的字符变量均以ch为前缀,若是指针变量则追加前缀p.如果一个变量由ppch开头，则表明它是指向字符指针的指针. “匈牙利”法最大的缺点是烦琐，例如 int i， j, k; float x, y， z； 倘若采用“匈牙利”命名规则,则应当写成 int iI， iJ, ik； // 前缀 i表示int类型 float fX， fY， fZ； // 前缀 f表示float类型 如此烦琐的程序会让绝大多数程序员无法忍受。 总的说来，没有一种命名规则可以让所有的程序员赞同,且命名规则对软件产品而言并不是“成败悠关”的事,而且在不同的平台和不同的环境下编写的程序所应遵循的规则也不尽相同，所以我们只是追求制定一种令大多数项目成员满意的命名规则，并在项目中贯彻实施. 3.2。1 共性原则 本节论述的共性规则是被大多数程序员采纳的，我们应当在遵循这些共性规则的前提下，再扩充特定的规则，如3.2。2节 ☆ 【规则3.2。1-1】 标识符应当直观且可以拼读，可望文知意,不必进行“解码”; ☆ 【规则3。2.1—2】 标识符的长度应当符合“min-length ＆＆ max—information”原 则； ☆ 【规则3。2.1-3】 命名规则尽量与所采用的操作系统或开发工具的风格保持一致; ☆ 【规则3。2。1-4】 程序中不要出现仅靠大小写区分的相似的标识符。 13 ☆ 【规则3。2。1—5】 程序中不要出现标识符完全相同的局部变量和全局变量，尽管两 者的作用域不同而不会发生语法错误,但会使人误解； ☆ 【规则3。2。1—6】 变量的名字应当使用“名词”或者“形容词＋名词”； ☆ 【规则3.2。1—7】 全局函数的名字应当使用“动词”或者“动词＋名词\"（动宾词 组）； ☆ 【规则3.2。1-8】 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等； ☆ 【建议3.2.1-9】 尽量避免名字中出现数字编号,如Value1,Value2等，除非逻辑上的确需要编号； 注： 3。2。1 标识符最好采用英文单词或其组合，便于记忆和阅读，切忌使用汉语拼音来命 名，程序中的英文单词一般不要太复杂，用词应当准确,例如不要把CurrentValue写成NowValue； 3。2。2 标示符的长度应当以最小的长度实现最多信息，一般来说,长名字能更好地表 达含义，但并非长的变量名就一定要比短的变量名要好，此外单字符的名字也是有用的,常见的如i,j,k,m,n,x,y，z等,它们通常可用作函数内的局部变量； 3.2.3 不同的操作系统的程序设计风格是不一样的，例如Windows应用程序的标识符通 常采用“大小写”混排的方式，如AddChild,而Unix应用程序的标识符通常采用“小写加下划线\"的方式，如add_child,别把这两类风格混在一起使用; 3.2.2 Windows变量命名规则 ☆ 【规则3。2.2-1】 变量的命名规则要求采用“匈牙利法则\"，即开头字母用变量的类型， 其余部分用变量的英文意思或其英文意思的缩写，尽量避免采用中文拼音，要求单词的第一个字母大写； 即：变量名＝变量类型＋变量英文意思(或缩写) 变量类型请参见附表1－变量类型表; ☆ 【规则3。2。2-2】 类名和函数名用大写字母开头的单词组合而成；对struct、union、 class变量的命名要求定义的类型用大写，结构采用S开头,联合体采用U开头，类采用C开头； 例如: struct SPoint 14 ｛ int m_nX； int m_nY; ｝； union URecordLen { } class CNode { }； ☆ 【规则3.2。2-3】 指针变量命名的基本原则为： 一重指针变量的基本原则为: 变量名＝ “p\"＋变量类型前缀＋命名 //类成员变量或成员函数 BYTE m_byRecordNum； BYTE m_byRecordLen； 对多重指针变量的基本原则为： 二重指针: 变量名＝“pp”＋变量类型前缀＋命名 三重指针： 变量名＝“ppp”＋变量类型前缀＋命名 .。。。。。 例如一个short＊型的变量应该表示为pnStart; ☆ 【规则3。2.2—4】 全局变量用g_开头；例如一个全局的长型变量定义为 15 g_lFileNum， 即：变量名＝g_＋变量类型＋变量的英文意思（或缩写）; ☆ 【规则3.2.2—5】 静态变量采用s_开头；例如一个静态的指针变量定义为s_plPrevInst, 即：变量名＝s_＋变量类型＋变量的英文意思（或缩写）; ☆ 【规则3。2.2—6】 m_lCount, 类成员变量采用m_开头；例如一个长型成员变量定义为 即：变量名＝m_＋变量类型＋变量的英文意思（或缩写)； ☆ 【规则3.2。2-7】 对const的变量要求在变量的命名规则前加入c_(若作为函数的输入 参数，可以不加)， 即：变量名＝c_＋变量命名规则,例如: const char＊ c_szFileName； ☆ 【规则3。2。2-8】 对枚举类型(enum）中的变量，要求用枚举变量或其缩写做前缀, 且用下划线隔离变量名，所有枚举类型都要用大写,例如: enum ｛ }； ☆ 【规则3.2。2—9】 对常量(包括错误的编码）命名，要求常量名用大写,常量名用英 文意思表示其意思，用下划线分割单词，例如： #define CM_7816_OK 0x9000； ☆ 【规则3.2。2—10】 为了防止某一软件库中的一些标识符和其它软件库中的冲突，可 以为各种标识符加上能反映软件性质的前缀。例如三维图形标准OpenGL的所有库函数均以gl开头,所有常量（或宏定义）均以GL开头。 EMDAYS_MONDAY; EMDAYS_TUESDAY； 。。..。。 EMDAYS 16 3.3 程序风格 程序风格虽然不会影响程序的功能，但会影响程序的可读性，追求清晰、美观，是程序风格的重要构成因素. 3.3.1 空行 空行起着分隔程序段落的作用。空行得体（不过多也不过少）将使程序的布局更加清晰.空行不会浪费内存，虽然打印含有空行的程序是会多消耗一些纸张，但是值得。 ☆ 【规则3.3.1—1】 在每个类声明之后、每个函数定义结束之后都要加空行.参见示例3。 3。1（a)； ☆ 【规则3.3.1—2】 在一个函数体内，逻揖上密切相关的语句之间不加空行，其它地方 应加空行分隔。参见示例3。3.1（b)； // blank line void Function1（…) { … } // blank line void Function2(…） { … } // blank line void Function3（…） // blank line while （condition） ｛ statement1; // blank line if (condition） ｛ } else ｛ statement3; statement2; 17 ｛ … } ｝ // blank line statement4; ｝ 示例3.3。1(a） 函数之间的空行 示例3。3.1(b） 函数内部的空行 3。3.2 代码行 ☆ 【规则3。3.2—1】 一行代码只做一件事情，如只定义一个变量，或只写一条语句， 这样的代码容易阅读，并且方便于写注释; ☆ 【规则3。3。2—2】 if、for、while、do等语句自占一行，执行语句不得紧跟其后， 不论执行语句有多少都要加｛}，这样可以防止书写失误； ☆ 【规则3。3。2-3】 if、for、while、do等语句的“{”要单独占用一行； ☆ 【建议3。3。2-1】 所有函数内的变量都在函数开始处定义； ☆ 【建议3.3.2-2】 尽可能在定义变量的同时初始化该变量(就近原则),如果变量的引用 处和其定义处相隔比较远，变量的初始化很容易被忘记。如果引用了未被初始化的变量，可能会导致程序错误,本建议可以减少隐患。 示例3.3.2（a)为风格良好的代码行，示例3.3。2（b）为风格不良的代码行. int nWidth; // width int nHeight; int nDepth； x = a + b; y = c + d; z = e + f； 18 // height // depth X ＝ a + b； y = c + d; z = e + f； int nWidth，nHight，nDepth；//width,height,depth if (nWidth 〈 nHight) { ｝ for （initialization; condition； update) { DoSomething（); } // blank line Other（)； for （initialization； condition； update） DoSomething(）； Other（); DoSomething(）； if (nWidth < nHight） DoSomething(）; 示例3。3.2（a） 风格良好的代码行 示例3。3.2（b) 风格不良的代码行 3.3。3 代码行内的空格 ☆ 【规则3.3.3—1】 关键字之后要留空格，象const、virtual、inline、case 等关键字之后 至少要留一个空格，否则无法辨析关键字，象if、for、while等关键字之后应留一个空格再跟左括号‘('，以突出关键字； ☆ 【规则3.3。3—2】 函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别; ☆ 【规则3.3。3-3】 ‘(’向后紧跟，‘）'、‘,’、‘;'向前紧跟，紧跟处不留空格; ☆ 【规则3.3。3-4】 ‘,'之后要留空格,如Function（x， y， z），如果‘;'不是一行的结束符号，其后要留空格,如for （initialization； condition; update）； ☆ 【规则3.3。3-5】 赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=\" “〉=”、“<=”、“+”、“*”、“%”、“＆＆”、“||\"、“〈〈”,“^”等二元操作符的前后应当加空格; ☆ 【规则3.3.3-6】 一元操作符如“!\"、“～”、“++”、“--”、“&”(地址运算符）等前后 不加空格； ☆ 【规则3.3。3—7】 象“［]\"、“。”、“—>”这类操作符前后不加空格; 19 ☆ 【建议3。3.3—1】 对于表达式比较长的for语句和if语句，为了紧凑起见可以适当 地去掉一些空格，如for （i=0； i<10； i++）和if (（a<=b) ＆& （c〈=d)) void Func1(int x, int y， int z); // favorable style void Func1 (int x，int y,int z）; // ill style if (year 〉= 2000) // favorable style if(year〉=2000） // ill style if （（a〉=b) ＆＆ (c<=d）) // favorable style if(a〉=b&＆c<=d） // ill style for （i=0; i<10； i++) // favorable style for(i=0;i〈10;i++） // ill style for (i = 0; I 〈 10； i ++) // favorable style x = a 〈 b ? a : b； // favorable style x=a〈b？a：b； // ill style int *x = ＆y; // favorable style int * x = & y； // ill style array［5］ = 0; // Do not use array [ 5 ］ = 0; a.Function(); // Do not use a . Function(）; b—〉Function（）； // Do not use b -〉 Function（); 示例3.3.3 代码行内的空格 3。3。4 对齐 ☆ 【规则3.3.4-1】 程序的分界符‘{’和‘｝’应独占一行并且位于同一列，同时与引 用它们的语句左对齐; ☆ 【规则3.3。4-2】 ｛ }之内的代码块在‘{’右边数格处左对齐； ☆ 【规则3。3。4.3】 代码的的对齐采用TAB键而不采用空格键对齐，一般TAB键设 置为向后空4个空格。 20 示例3。3。4（a）为风格良好的对齐，示例3。3.4(b)为风格不良的对齐。 void Function（int x） { … // program code } if （condition) { … // program code ｝ else ｛ … // program code ｝ for （initialization; condition； update) ｛ … // program code } While (condition) ｛ … // program code } 如果出现嵌套的{｝，则使用缩进对齐，如: { … } while (condition){ … // program code } for （initialization; condition； update）{ … // program code } else { … // program code ｝ void Function(int x）{ … // program code ｝ if （condition){ … // program code 21 … ｝ { … } 示例3。3.4（a) 风格良好的对齐 示例3。3.4（b) 风格不良的对 齐 3.3.5 长行拆分 ☆ 【规则3。3。5—1】 代码行最大长度宜控制在70至80个字符以内; ☆ 【规则3.3。5—2】 长表达式要在低优先级操作符处拆分成新行，操作符放在新行之 首（以便突出操作符）,拆分出的新行要进行适当的缩进，使排版整齐，语句可读. if （(very_longer_variable1 〉= very_longer_variable12） ＆& （very_longer_variable3 〈= very_longer_variable14) ＆＆ (very_longer_variable5 〈= very_longer_variable16)) { DoSomething（); ｝ virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix， CMatrix rightMatrix）； for （very_longer_initialization； { very_longer_condition; very_longer_update) 22 } 示例3。3.5 长行的拆分 DoSomething（); 3。3。6 修饰符的位置 修饰符 ＊ 和 ＆ 应该靠近数据类型还是该靠近变量名，是个有争议的活题，若将修饰符 ＊ 靠近数据类型，例如：int* x; 从语义上讲此写法比较直观，即x是int 类型的指针，上述写法的弊端是容易引起误解,例如：int＊ x, y; 此处y容易被误解为指针变量.虽然将x和y分行定义可以避免误解，但并不是人人都愿意这样做。 ☆ 【规则3。3.6-1】 应当将修饰符 * 和 ＆ 紧靠变量名； 3.3.7 注释 C语言的注释符为“/*…＊/”。C++语言中，程序块的注释常采用“/＊…*/”，行注释一般采用“//…”.注释通常用于： （1）版本、版权声明; （2）函数接口说明； （3）重要的代码行或段落提示。 虽然注释有助于理解代码，但注意不可过多地使用注释.参见示例3.3.7。 ☆ 【规则3。3.7—1】 注释是对代码的“提示”,而不是文档，程序中的注释不可喧宾 夺主，注释太多了会让人眼花缭乱，注释的花样要少； ☆ 【规则3。3。7-2】 如果代码本来就是清楚的，则不必加注释；例如 i++; // i 加 1，多余的注释 ☆ 【规则3。3。7-3】 边写代码边注释，修改代码同时修改相应的注释，以保证注释与 代码的一致性，不再有用的注释要删除; ☆ 【规则3.3.7—4】 注释应当准确、易懂，防止注释有二义性,错误的注释不但无益反而 有害; ☆ 【规则3。3.7—5】 尽量避免在注释中使用缩写，特别是不常用缩写； ☆ 【规则3。3.7-6】 注释的位置应与被描述的代码相邻,可以放在代码的上方或右方，不 可放在下方； 23 ☆ 【规则3。3。7—8】 当代码比较长，特别是有多重嵌套时，应当在一些段落的结束处 加注释，便于阅读; ☆ 【建议3。3.7—9】 对于多行代码的注释，尽量不采用“/*..。＊/”,而采用多行“//” 注释，这样虽然麻烦,但是在做屏蔽调试时不用查找配对的“/＊。..*/”。 //////////////////////////////////////////////////////////////////// if (…) // Function capacity： // Parameter declare： // Return value ： //////////////////////////////////////////////////////////////////// void Function（float x， float y， float z) ｛ … } 示例3.3。7 程序的注释 { … while (…） ｛ … } // end of while … ｝ // end of if 3。7。1 文件头的注释 文件头的注释请参见3.1，文件头的注释是以两行斜杠开始，以两行斜杠结束(以区别于 函数的注释）。 3。7.2 函数头的注释 一般说来每个函数都应该做详细的注释，函数头的注释是以一行斜杠开始，以一行斜杠结束，注释的内容包括“功能”，“参数”,“返回值”，“设计思想”，“调用函数\"，“日期\"，“修改记录”等几个方面，函数头的注释格式如下: ////////////////////////////////////////////////////////////////////////////////////////////// // Function capacity : Describe the function capacity 24 // Parameter declare ： // parameter 1： Describe the function of parameter （ input/output parameter ) // parameter 2： // ....。. // Return value ： Describe the possible return value // Designed idea ： Describe designed idea about the function // Author : Describe the function of parameter （ input/output parameter ） // Creation date ： Creation date（YY-MM-DD） // Transferred function： // Modification record： // （一）Mender 1： Modified date: modified content List the sub—function in the function ////////////////////////////////////////////////////////////////////////////////////////////// 25 3。4 函数设计 函数是C++/C程序的基本功能单元，其重要性不言而喻。函数设计的细微缺点很容易导致该函数被错用，所以光使函数的功能正确是不够的。本章重点论述函数的接口设计和内部实现的一些规则。 函数接口的两个要素是参数和返回值。C语言中，函数的参数和返回值的传递方式有两种：值传递（pass by value)和指针传递（pass by pointer）。C++ 语言中多了引用传递（pass by reference）。由于引用传递的性质象指针传递,而使用方式却象值传递,初学者常常迷惑不解，容易引起混乱，请先阅读3。4.6节“引用与指针的比较”。 3.4.1 参数的规则 ☆ 【规则3.4。1-1】 参数的书写要完整,不要贪图省事只写参数的类型而省略参数名字， 如果函数没有参数,则用void填充；例如： void SetValue（int nWidth, int nHeight); void SetValue（int, int）; float GetValue（void）; float GetValue（）； ☆ 【规则3。4.1—2】 // 良好的风格 // 不良的风格 // 良好的风格 // 不良的风格 参数命名要恰当，顺序要合理； 例如编写字符串拷贝函数StringCopy，它有两个参数，如果把参数 名字起为str1和str2,例如： void StringCopy（char *str1, char ＊str2)； 那么我们很难搞清楚究竟是把str1拷贝到str2中,还是刚好倒过来,可以把参数名字起得更有意义，如叫strSource和strDestination。这样从名字上就可以看出应该把strSource拷贝到strDestination.还有一个问题,这两个参数那一个该在前那一个该在后？参数的顺序要遵循程序员的习惯.一般地，应将目的参数放在前面，源参数放在后面。如果将函数声明为： void StringCopy（char *strSource， char ＊strDestination）; 别人在使用时可能会不假思索地写成如下形式: 26 char str［20］； StringCopy(str， “Hello World”）； // 参数顺序颠倒 ☆ 【规则3.4。1—3】 如果参数是指针，且仅作输入用，则应在类型前加const，以防止该指针在函数体内被意外修改。例如： void StringCopy(char *strDestination,const char *strSource）; ☆ 【规则3。4.1-4】 如果输入参数以值传递的方式传递对象，则宜改用“const &”方式 来传递，这样可以省去临时对象的构造和析构过程,从而提高效率； ☆ 【建议3。4.1-1】 避免函数有太多的参数,参数个数尽量控制在5个以内。如果参数太 多,在使用时容易将参数类型或顺序搞错； ☆ 【建议3.4。1-2】 尽量不要使用类型和数目不确定的参数； C标准库函数printf是采用不确定参数的典型代表，其原型为： int printf(const chat *format[, argument]…）； 这种风格的函数在编译时丧失了严格的类型安全检查. 3。4.2 返回值的规则 ☆ 【规则3。4。2—1】 不要省略返回值的类型； C语言中，凡不加类型说明的函数，一律自动按整型处理，这样做不会有什么好处，却容易被误解为void类型； C++语言有很严格的类型安全检查，不允许上述情况发生。由于C++程序可以调用C函数,为了避免混乱,规定任何C++/ C函数都必须有类型。如果函数没有返回值，那么应声明为void类型 ☆ 【规则3.4。2—2】 函数名字与返回值类型在语义上不可冲突; 违反这条规则的典型代表是C标准库函数getchar。 例如： char c； c = getchar(）; if （c == EOF) 27 … 按照getchar名字的意思，将变量c声明为char类型是很自然的事情。但不幸的是getchar的确不是char类型,而是int类型，其原型如下： int getchar(void）; 由于c是char类型，取值范围是[-128，127]，如果宏EOF的值在char的取值范围之外，那么if语句将总是失败，这种“危险”人们一般哪里料得到!导致本例错误的责任并不在用户，是函数getchar误导了使用者 ☆ 【规则3。4.2-3】 不要将正常值和错误标志混在一起返回。正常值用输出参数获得， 而错误标志用return语句返回; ☆ 【建议3.4。2-1】 有时候函数原本不需要返回值,但为了增加灵活性如支持链式表达， 可以附加返回值； 例如字符串拷贝函数strcpy的原型： char *strcpy（char *strDest,const char ＊strSrc); strcpy函数将strSrc拷贝至输出参数strDest中，同时函数的返回值又是strDest。这样做并非多此一举,可以获得如下灵活性: char str[20］; int nLength = strlen（ strcpy（str， “Hello World”） ); ☆ 【建议3。4.2—2】 如果函数的返回值是一个对象，有些场合用“引用传递\"替换“值传递”可以提高效率。而有些场合只能用“值传递”而不能用“引用传递”，否则会出错； 对于建议3。4。2—2,如果函数的返回值是一个对象，有些场合用“引用传递”替换“值 传递\"可以提高效率，而有些场合只能用“值传递”而不能用“引用传递”，否则会出错,例如： class String {… // 赋值函数 String＆ operate=（const String ＆other)； 28 // 相加函数，如果没有friend修饰则只许有一个右侧参数 friend private: ｝； String的赋值函数operate = 的实现如下: String ＆ String：:operate=(const String ＆other) { ｝ 对于赋值函数,应当用“引用传递”的方式返回String对象。如果用“值传递”的方式，虽然功能仍然正确，但由于return语句要把 *this拷贝到保存返回值的外部存储单元之中，增加了不必要的开销，降低了赋值函数的效率.例如： String a，b，c; … a = b； // 如果用“值传递”，将产生一次 ＊this 拷贝 if （this == ＆other) return *this； char ＊m_data； String operate+（ const String &s1, const String &s2）； delete m_data； m_data = new char［strlen（other。data）+1]; strcpy（m_data， other。data)； return *this； // 返回的是 ＊this的引用，无需拷贝过程 a = b = c； // 如果用“值传递”，将产生两次 ＊this 拷贝 String的相加函数operate + 的实现如下： String operate+（const String ＆s1, const String ＆s2） { 29 ｝ String temp; delete temp。data； // temp。data是仅含‘\\0’的字符串 temp。data = new char[strlen(s1.data） + strlen(s2.data) +1]; strcpy(temp.data, s1.data)； strcat（temp。data, s2。data); return temp； 对于相加函数，应当用“值传递”的方式返回String对象。如果改用“引用传递”，那么函数返回值是一个指向局部对象temp的“引用”。由于temp在函数结束时被自动销毁，将导致返回的“引用”无效。例如: c = a + b； 此时 a + b 并不返回期望值，c什么也得不到，流下了隐患。 3.4。3 函数内部实现的规则 不同功能的函数其内部实现各不相同,看起来似乎无法就“内部实现”达成一致的观点。但根据经验，我们可以在函数体的“入口处\"和“出口处\"从严把关，从而提高函数的质量。 ☆ 【规则3。4。3-1】 在函数体的“入口处”,对参数的有效性进行检查; 很多程序错误是由非法参数引起的,我们应该充分理解并正确使用“断言”(assert）来防止此类错误。详见4.5节“使用断言” ☆ 【规则3。4.3—2】 注意事项如下： (1) return语句不可返回指向“栈内存\"的“指针”或者“引用”，因为该内存在函数体结束 时被自动销毁，例如： char ＊ Func(void） ｛ char str[] = “hello world”； // str的内存位于栈上 在函数体的“出口处”，对return语句的正确性和效率进行检查； 30 ｝ … return str; // 将导致错误 (2） 要搞清楚返回的究竟是“值”、“指针”还是“引用\"; （3) 如果函数返回值是一个对象，要考虑return语句的效率,例如： return String(s1 + s2）; 这是临时对象的语法，表示“创建一个临时对象并返回它\"，不要以为它与“先创建一 个局部对象temp并返回它的结果”是等价的，如 String temp（s1 + s2）； return temp; 实质不然，上述代码将发生三件事。 首先，temp对象被创建，同时完成初始化； 然后拷贝构造函数把temp拷贝到保存返回值的外部存储单元中； 最后，temp在函数结束时被销毁（调用析构函数)。 然而“创建一个临时对象并返回它”的过程是不同的，编译器直接把临时对象创建并初始化在外部存储单元中,省去了拷贝和析构的化费，提高了效率。 类似地，我们不要将 return int(x + y）； // 创建一个临时变量并返回它 写成 int temp = x + y; return temp; 由于内部数据类型如int,float,double的变量不存在构造函数与析构函数，虽然该“临时变量的语法”不会提高多少效率，但是程序更加简洁易读. 31 3.4。4 其它建议 ☆ 【建议3。4。4—1】 函数的功能要单一,不要设计多用途的函数； ☆ 【建议3。4.4-2】 函数体的规模要小，尽量控制在150行代码之内； ☆ 【建议3。4。4—3】 尽量避免函数带有“记忆”功能。相同的输入应当产生相同的输 出带有“记忆”功能的函数，其行为可能是不可预测的，因为它的行为可能取决于某种“记忆状态”。这样的函数既不易理解又不利于测试和维护。在C/C++语言中,函数的static局部变量是函数的“记忆”存储器。建议尽量少用static局部变量，除非必需. ☆ 【建议3.4.4—4】 不仅要检查输入参数的有效性，还要检查通过其它途径进入函数体 内的变量的有效性,例如全局变量、文件句柄等； ☆ 【建议3.4。4—5】 用于出错处理的返回值一定要清楚，让使用者不容易忽视或误解 错误情况。 3.4.5 使用断言 程序一般分为Debug版本和Release版本，Debug版本用于内部调试，Release版本发行给用户使用。 断言assert是仅在Debug版本起作用的宏，它用于检查“不应该”发生的情况。示例4。5是一个内存复制函数。在运行过程中，如果assert的参数为假，那么程序就会中止（一般地还会出现提示对话，说明在什么地方引发了assert）。 void ＊memcpy(void ＊pvTo, const void ＊pvFrom， size_t size） { assert((pvTo != NULL） ＆＆ （pvFrom ！= NULL)）; // 使用断言 byte *pbTo = (byte ＊) pvTo； // 防止改变pvTo的地址 byte ＊pbFrom = （byte ＊） pvFrom； // 防止改变pvFrom的地址 while（size -— > 0 ） *pbTo ++ = ＊pbFrom ++ ； 32 } 示例3。4。5 复制不重叠的内存块 assert不是一个仓促拼凑起来的宏。为了不在程序的Debug版本和Release版本引起差别，assert不应该产生任何副作用。所以assert不是函数,而是宏.程序员可以把assert看成一个在任何系统状态下都可以安全使用的无害测试手段。如果程序在assert处终止了，并不是说含有该assert的函数有错误，而是调用者出了差错，assert可以帮助我们找到发生错误的原因。 return pvTo; ☆ 【规则3.4。5—1】 使用断言捕捉不应该发生的非法情况，不要混淆非法情况与错误 情况之间的区别，后者是必然存在的并且是一定要作出处理的; ☆ 【规则3。4.5—2】 在函数的入口处，使用断言检查参数的有效性（合法性）； ☆ 【建议3。4.5—1】 在编写函数时，要进行反复的考查，并且自问：“我打算做哪些假定？\"一旦确定了的假定，就要使用断言对假定进行检查; ☆ 【建议3.4。5—2】 一般教科书都鼓励程序员们进行防错设计，但要记住这种编程风 格可能会隐瞒错误.当进行防错设计时，如果“不可能发生”的事情的确发生了，则要使用断言进行报警. 3。4。6 引用与指针的比较 引用是C++中的概念，初学者容易把引用和指针混淆一起.一下程序中,n是m的一个引用(reference），m是被引用物（referent）. int m; int ＆n = m； n相当于m的别名（绰号），对n的任何操作就是对m的操作。所以n既不是m的拷贝,也不是指向m的指针，其实n就是m它自己. 引用的一些规则如下： （1） 引用被创建的同时必须被初始化(指针则可以在任何时候被初始化）； （2） 不能有NULL引用，引用必须与合法的存储单元关联（指针则可以是NULL)； （3） 一旦引用被初始化，就不能改变引用的关系（指针则可以随时改变所指的对象）。 以下示例程序中，k被初始化为i的引用.语句k = j并不能将k修改成为j的引用,只是把k的值改变成为6。由于k是i的引用，所以i的值也变成了6。 33 int i = 5; int j = 6; int ＆k = i; k = j； // k和i的值都变成了6; 上面的程序看起来象在玩文字游戏，没有体现出引用的价值.引用的主要功能是传递函数的参数和返回值。C++语言中，函数的参数和返回值的传递方式有三种：值传递、指针传递和引用传递. 以下是“值传递”的示例程序。由于Func1函数体内的x是外部变量n的一份拷贝，改变x的值不会影响n， 所以n的值仍然是0。 void Func1(int x) ｛ ｝ … int n = 0； Func1（n)； cout 〈〈 “n = ” << n <〈 endl; // n = 0 x = x + 10； 以下是“指针传递\"的示例程序。由于Func2函数体内的x是指向外部变量n的指针，改变该指针的内容将导致n的值改变，所以n的值成为10。 void Func2（int ＊x) { ｝ … （* x) = （* x） + 10; 34 int n = 0； 以下是“引用传递\"的示例程序。由于Func3函数体内的x是外部变量n的引用，x和n是同一个东西，改变x等于改变n，所以n的值成为10。 void Func3(int ＆x) { ｝ … int n = 0； Func3（n）; 对比上述三个示例程序，会发现“引用传递”的性质象“指针传递”，而书写方式象“值传递”。 cout<〈 “n = ” 〈< n<〈 endl； // n = 10 x = x + 10; Func2（&n）; cout 〈〈 “n = ” 〈< n 〈〈 endl; // n = 10 3。5 变量类型定义 类 型 bool(BOOL) byte（BYTE) short（SHORT) int（INT) long(LONG) char(CHAR） unsigned short(WORD) 规 则 用b开头 用n开头 用n开头 用l开头 范 例 bIsParent nFileLen nStepCount lSize 用by开头 byFlag 用ch开头 chCount 用w开头 wLength unsigned long(DWORD） 用dw开头 dwBroad void（VOID） 用v开头 vVariant 用0结尾的字符串 用sz开头 szFileName 35 LPCSTR(LPCTSTR) struct BYTE＊ WORD* LONG＊ 用str开头 strString hHandle 用blk开头 blkTemplate 用pb开头 pbValue 用pw开头 pwValue 用pl开头 plValue HANDLE（HINSTANCE） 用h开头 四、软件测试规范 为了确保软件产品质量，使产品能够顺利交付和通过验收,特编写软件测试规范,以作参考 测试的依据来源于《系统需求说明书》、《详细设计》、《技术协议》等有关资料。开发人员按照需求说明书进行软件开发和测试. 测试之前要明确每次测试的目的，必要时可以编写《测试计划》，必须明确采用的测试环境、工具和测试软件；采用的测试用例、测试数据和预期的结果，以达到不放过一个小的bug。 下面介绍几种常用的方法，仅作参考，如果开发人员有好的测试方法,可以随时添加该文档的内容。 4.1 单元测试 项目开发实现过程中，每个程序单元(程序单元的划分视具体开发工具而定，一般定为函数或子程序级）编码调试通过后，要及时进行单元测试。 单元测试由使用白盒测试方法，根据程序单元的控制流程，争取达到分支覆盖。对于交互式运行的产品，不便于进行自动测试的，可以采用功能测试的方法进行。 单元测试针对程序模块,从程序的内部结构出发设计测试用例。多个模块可以独立进行单元测试. ➢ 单元测试内容包括模块接口测试、局部数据结构测试、路径测试、错 误处理测试等； ➢ 单元测试组织原则一遍根据开发进度安排对已开发完成的单一模块 进行测试； 单元测试停止标准：完成了所有规定单元的测试,单元测试中发现的bug已经得到修改。 36 4。2 系统测试 在项目开发完成之后，应对整个系统软件和硬件进行系统测试。对性能、可靠性、健壮性、压力承受力等方面分别进行评价，以验证系统是否满足规定的需要. 系统测试一般进行如下几种情况的测试： ➢ 正常情况 ➢ 非正常情况 ➢ 破坏性测试 ➢ 边界情况 ➢ 非法情况 ➢ 强度测试 ➢ 性能测试 ➢ 兼容性测试 ➢ 用户友好性测试 界面设计规范测试: ➢ 光标的初始位置 ➢ 字体是否统一 ➢ 字号是否符合规定 ➢ 标题颜色 ➢ 按钮的名称是否规范 ➢ 界面布局是否合理，整体效果如何 输入值测试： ➢ 数据类型 ➢ 数据长度 ➢ 约束条件是否满足，是否完整 ➢ TAB和Enter键是否起作用 ➢ 键盘操作能否全部代替鼠标操作 ➢ 输入（光标）是否按照顺序前进 按钮测试： 37 ➢ 将按钮放开和封闭是否严格、准确，不能使用的按钮必须封闭 ➢ 检查“退出”、“取消\"等具有共性按钮的功能 异常情况测试： 在完成正常功能测试后,安正常处理的相同操作顺序，执行与正常处理不同的动作例如 ➢ 正常处理中要求输入日期的字段，这时输入字符或数字 ➢ 正常处理中输入字段有范围要求，这时输入超过范围的值 ➢ 正常处理中用两个值限定范围,这时用一个值或不限定 ➢ 正常处理中要求用“Tab”键，这时安“Enter\"键或其他键 ➢ 正常处理中单选框、多选框、下拉框等，十一偶那个非指定键操作 ➢ 使用不同于指定的按钮操作 4.6 业务测试 在系统测试结束后，均可由最终用户或测试人员对系统进行测试。业务测试着重测试业务流程,功能、用户界面等方面。 4。7 验收测试 提交验收的软件系统版本要求如下： ➢ 完成了单元测试、系统测试和业务测试。 ➢ 软件版本满足设计定义的各项功能、性能要求 ➢ 提交的数据库脚本样本需要完整，没有冗余数据 ➢ 在所有测试中发现的bug已经得到解决，各级缺陷修改率达到标准 ➢ 软件需求分析说明书中定义的所有功能都已经实现，性能指标全部达 到性能需求指标 ➢ 所有文档齐备完整 4.8 用户现场测试 将软件部署到用户实际生产环境后，由于环境差异，需要在用户现场进行确认测试，保证系统功能、性能完备，可正常运行。测试内容： ➢ 根据软件系统规模，准备现场测试用例,涵盖所有重要功能点，若规 38 模小，需要将全部功能点全部测试一遍 ➢ 对于后台已定义好的工作流、功能栏目路径以及用户信息等数据，不 可进行修改和删除操作,新增的测试数据也需要在测试完成后给予清楚 ➢ 重点检查上传、下载的数据是否可以正常的打开或保存 ➢ 确认界面美观,基本信息和链接无错误 ➢ 考虑用户实际的软件环境和网络环境，以客户端最为复杂的软硬件环 境作为测试机器,检查有无异常情况出现 针对前期发现的bug进行回归测试，以保证发布版本为最新版本。 五、软件版本管理 4。1版本管理的必要性 软件项目完全由一个人来完成是难以想象的,通常是有一个研发小组来共同分析、设计、编码和维护.许多因素都有可能导致对软件的修改，小的可能只是对某个源文件中的某个变量的定义改动，大到重新设计程序模块甚至可能是整个需求分析变动。由于软件开发所固有的特征，可能会形成众多的软件版本，而且我们并不能保证不出现错误的修改.所以必须要进行版本管理。 以往的那种被誉为具有良好编程风格的做法，诸如在对他人的源程序进行修改时注释修改原因，修改人和日期，如果是多个成员同时进行了修改，那么需要进行及时的人工的差异比较和综合以便形成一个统一的新版本.这种做法在当前的大型软件的开发中已经越来越没有空间了，可以说是一种以小作坊的形式来面对软件的社会化大生产，再也不可能行得通了，这样会出现版本控制问题. 版本控制出现问题就会出现,代码管理混乱、解决代码冲突困难、在代码整合期间引入深层BUG、无法对代码的拥有者进行权限控制，特别是对产品的开发，你会频繁的进行版本发布，这时如果没有一个有效的管理产品版本的工具，一切将变得非常艰难 1. 怎样对研发项目进行整体管理； 2. 项目开发小组的成员之间如何以一种有效的机制进行协调； 3。 如何进行对小组成员各自承担的子项目的统一管理； 39 4。 如何对研发小组各成员所作的修改进行统一汇总； 5。 如何保留修改的轨迹，以便撤销错误的改动； 6. 对在研发过程中形成的软件的各个版本如何进行标识，管理及差异识辨. 我们必须要引进一种管理机制，一个版本管理机制，而且是广义上的版本管理，它不仅需要对源代码的版本进行管理，而且还要对整个项目进行管理，必须使用版本控制工具。 40 因篇幅问题不能全部显示，请点此查看更多更全内容