1、xxx 科技有限公司程序员生存手册2014编程规范、文档注释规范、测试流程黄硕XXX 科技有限公司研发部 | 深圳市 xxxxxxxxx 科技有限公司程序员生存手册xxx 科技有限公司程序员生存手册文件修改历史修改时间 修改人 简单描述10/17/2014 黄硕 创建宝捷信科技有限公司程序员生存手册0目录序言 0编程规范 .0命名规则 0命名空间 .0类 0成员变量 .1成员函数 .1模板 1友缘类 .2友缘函数 .2全局变量 .2静态变量 .2非成员函数 .2块规则 2垂直距离 4命名空间规则 .5指针数组规则 .6尽量使用 const.6所有的变量都必须初始化 .6所有的.cpp/.c 文
2、件都需要有一个对应的.h 文件 6头文件应用的次序 7宝捷信科技有限公司1单参数构造函数需加 explicit 关键字 .7需要自己定义默认的构造函数 7Structs vs Classes.7初始化成员变量 .8声明的顺序 .8Casting 8使用公司定义的类型 8严禁类的循环依赖 9注释规范 .9基本注释 9命名空间注释 .10类注释 12方法注释 13变量注释 15Doxygen 使用教程 .15测试流程 .24静态测试 24单元测试 27代码审查 32内存测试 33测试文档模板 .33总结 34宝捷信科技有限公司2引用 34附录 34图表图 0-113图 0-214图 0-315图
3、0-416图 0-516图 0-617图 0-717图 0-818图 0-919图 0-1020图 0-1120图 0-1221图 0-1322图 0-1423图 0-1523图 0-16、 24图 0-1725图 0-1825宝捷信科技有限公司3图 0-1926图 0-2027图 0-128图 0-230图 0-331图 0-432图 0-533图 0-634图 0-735宝捷信科技有限公司程序员生存手册0序言软件的开发不仅仅是写代码这么简单，一段代码从程序员的编辑器里诞生，到成为一个可以被依赖的组件需要花费写代码三倍的时间。一段代码能够成为一个可以和其他组件互通的组成部分又需要三倍的努力。
4、这段代码最终成为一个可靠、可扩展、可维护、可互通的部分需要总共九倍的时间。本文将详细阐述一套理念、一套规范，帮助公司将代码的质量管理提升到一个新的层面上来。编程规范此处的编程规范目前只是草稿，尚待商榷。命名规则命名空间命名空间一律采用 UpperCamelCase 例如namespacePSMoldProtector类类也需要采用 UpperCamelCase 例如classPSBaseAlg宝捷信科技有限公司1;成员变量成员变量建议采用 lowerCamelCase 外加一个下划线例如PSBaseAlgInputParaminputParam_;而对应的 Getter/Setter 则可以写
5、为，PSBaseAlgInputParaminputParam() const;constintinputParam(constPSBaseAlgInputParam这样看起来更简洁。成员函数成员函数建议使用 lowerCamerCase, 例如voidsetData(void * data);模板建议尽量使用少量的模板，因为模板容易造成生成的代码量剧增。如果用到模板建议template模板的类型名称用有含义的名称，使用 UpperCamelCase, 而不是简单地 T1, T2。模板的宝捷信科技有限公司2参数用 lowerCamelCase。友缘类尽量少使用友缘类因为会破坏 OO 的完整性。
6、如果一定要用，建议前面加一个 f。友缘函数尽量少使用友缘函数因为会破坏 OO 的完整性。如果一定要用，建议前面加一个 f。全局变量全局变量建议前面加个 g，其他用 CamelCase。intgImageWidth;静态变量方法内定义的静态变量可以前面加个 s, 其他用 CamelCase。intsCount;非成员函数建议使用 lowerCamerCase, 例如voidsetData(void * data);宝捷信科技有限公司3块规则if else if (x = 1)else if (x = 2)elseIf 和 括号之间有一个空格，括号内的 x 和 1 与()之间无空格, while、
7、do while 和 switch 也遵循类似的规则。所有语句操作符与常数、变量名之间需要有空格，例如X = 2Y = x * (z + 10);If (0 = x)for (I = 0; I 0; +I, -j)for 循环， for 与 （之间需要有个空格，每个; 后面都跟一个空格，每个，后面都跟一个空格。所有的块不可省略，尽管内容只有一行。垂直距离每个方法的定义之间需要有一行距离void func1()；voidfunc2();实现之间也需要有一行距离voidfunc1()宝捷信科技有限公司5void func2()命名空间规则整个项目需要有一个自己的命名空间，例如namespacePS
8、MoldProtector 项目里面的模块又需要自己的命名空间namespacePSMoldProtectornamespacePSAlgorithm各个模块内部的子模块可以有自己的命名空间，例如namespacePSMoldProtectornamespacePSAlgorithm宝捷信科技有限公司6namespacePSMatchAlg这样做的目的是为了防止命名冲突，而各个模块内部的命名可以很自由很简洁。指针数组规则数组访问 arrayi + 1, 符号两侧需要一个空格。指针的访问尽量写成数组形式，提高可读性。例如，*（*(array + i) + j） = 100; 不如写成arrayi
9、j = 100;尽量使用 const尽量使用 const 提高安全性， 例如constintaddNumber(constint * constnum, constintaddon);int retrieve() const;所有的变量都必须初始化不写空的变量，所有变量声明时就要初始化。宝捷信科技有限公司7所有的.cpp/.c 文件都需要有一个对应的.h 文件.h 文件必须写引用保护#ifndef X_Y_H#define X_Y_H#endif头文件应用的次序1. C 库头文件2. C+库头文件3. 其他库头文件4. 自己定义的头文件单参数构造函数需加 explicit 关键字单参数构造函数
10、容易误用在隐式转换中，需添加 explicit。需要自己定义默认的构造函数不然编译器会自动生成，有时会影响正确性宝捷信科技有限公司8Structs vs Classes当只有数据时用 struct, 需要封装动作时用 class。初始化成员变量用 constructr():x(0), y(1),z（“xyz”）初始化变量，这样可以再 Object 创建周期最先初始化变量，避免错误。声明的顺序1. Typedefs, enums2. Constants3. Constructors4. Destructor5. Methods, including static methods6. Data M
11、embers, including static data membersCasting尽量使用 static_cast b Float thisIsAnotherFloat = 200.0;Char* x = “this is sooooo cool”;尽量用 std:string 替代 char*Std:string 操作更方便，出错的概率更小。宝捷信科技有限公司12尽量用 reference 替代指针Reference 更不易出错。注释规范注释的部分选用 Doxygen 工具和配套的注释规范以方便将注释直接提取为文档，方便以后查看和检索。基本注释/*! Some legal issue
12、declared here */基本注释用/*! 和 */作为一对。中间允许换行例如/*! Some legal issue declared here */也可以。 这里要说明的是 Doxygen 提供了几种注释的用法。 我们在这里统一用/*! */。命名空间注释namespace PSAlgorithmnamespace 是命名空间的标识符。宝捷信科技有限公司13/*! namespace PSAlgorithm所有算法相关的接口、实现、类都需要放到这个命名空间里。*/namespacePSAlgorithm这样写就会把这个命名空间的注释加到文档里的命名空间对应的文档里。效果如图 0-1,
13、 0-2， 0-3 所示。图 0-1宝捷信科技有限公司14图 0-2宝捷信科技有限公司15图 0-3类注释/*! class PSBaseAlgbrief 算法基类 author 黄硕version 1.0.0date 2014 年 10 月 13 日details 此类作为基类，永远不应被实例化。copyright 2014 所有版权归宝捷信所有。*/classPSBaseAlgclass 标注的是类名，生成文档时会将此注释放在类的专区里便于查阅。brief 后面是简介，details 是详细说明，二者是对应的。author 标注作者， version 标注版本， date 标注日期。 co
14、pyright 标注版权信息。 由于 doxygen 生成的是 html，我们也可以加入html 的特殊字符。例如在生成的文档显示的就是。Doxygen 会自动检测类的继承关系，画出继承关系图。宝捷信科技有限公司16生成的效果如图 0-4， 0-5 所示，图 0-4图 0-5宝捷信科技有限公司17方法注释/*! fnintapply(PSBaseAlg* preAlg)brief 通用的函数调用接口此接口适用于顺序调用。details 未来新设计的算法类继承这个接口，并将其重构。此接口适用于顺序调用。paramPSBaseAlg *preAlg 调用链的上一个调用算法类。return 返回错误
15、值（详情请查看自动生成的错误值对照表) 。*/virtualconstint apply(PSBaseAlg* preAlg) return 0; fn 代表注释方法，同样的brief 写方法的简介， details 写详细信息。 param 注释输入参数，可以用都哟个param 项在同一个方法的注释内。return 注释返回值。warning 注释警告信息。效果如图 0-6 所示。警告信息的效果如图 0-7 所示。图 0-6warning 永远不要调用！宝捷信科技有限公司18图 0-7变量注释/*! varPSBaseAlgInputParams *inParambrief 通用抽象的输入参
16、数。*/PSBaseAlgInputParams *inParam;var 注释变量，被注释的变量会被生成在文档的变量区域图 0-8Doxygen 使用教程在安装完 doxygen 在 Windows 之后，doxygen 会被安装到 X:/Program Files/doxygen，随着程序安装的还有一个前端 Doxywizard。打开 Windows 7/Windows 10 的开始菜单或Windows 8/Windows 8.1 的 Charm menu，在搜索栏输入 doxywizard。点击搜索出的应用程序运行。宝捷信科技有限公司19 图 0-9Doxywizard 的界面如图 0-
17、9 所示。宝捷信科技有限公司20 图 0-10第一步选择 Wizard 中的 Project 选项，填写 Project name, Project version。这些信息会出现在生成文档的抬头。图 0-11效果如图 0-11 所示。PSMoldProtectorAlgorithmMock 绑定的就是 Project name, 1.0.0 是Project version。然后在 Source code directory 处点击后面的 select 选择源代码的路径。如果你的源代码路宝捷信科技有限公司21境内有代码在子文件夹里可以勾选 scan recursively。最后在 Desti
18、nation directory 里选择生成文档的目标路径。点击 Next。图 0-12第二步进入到 Mode 的选择，在这里选择 Documented entities only （只生成写过注释的组件的文档） ，在语言里选择(C+ Output), 注意不是 C+/CLI， CLI 是.Net 特有的。然后点击 Next。宝捷信科技有限公司22 图 0-13第三步到了输出选项，这里我们选择 HTML，选择 with navigation panel(会在左侧增加一个导航栏，像 javadoc 一样便于查阅 )， 选择 With search function，会生成一个搜索框，可以搜索文档里的任何词，非常实用。LaTex 是一种专业的文档编写格式，写论文用的居多。我们在这里不用。Man Pages 是 Linux/Unix 下的 man page， RTF 可以被 word 打开，XML 写出来可以再与其他的服务相联接。此外你还可以点击 change color 更改生成文档的颜色基调。如图 0-14 所示。
