软件编码规范

1、软软软软软软件件件件件件编编编编编编码码码码码码规规规规规规范范范范范范 文件编号：rdc-ded-scs-spc-00 当前版本： 作 者： 审 核 人： 文件状态： 草稿 正式发布 正在修改 完成日期： 中国人民银行清算总中心 支付系统开发中心 文档修订记录 版本编号变化状态简要说明日期变更人批准日期批准人 注：变化状态：a增加，m修改，d删除 目目 录录 第一篇第一篇c/c+c/c+编码规范编码规范 .6 6 第一章第一章代码组织代码组织 .6 6 第二章第二章命名命名 .9 9 2.1文件命名 .9 2.2变量命名 .9 2.3常量与宏命名 .10 2.4类命名 .10 2.5函数命名

2、 .10 2.6参数命名 .11 第三章第三章注释注释 .1212 3.1文档化注释 .12 3.2语句块注释 .17 3.3代码维护注释 .20 第四章第四章编码风格编码风格 .2222 4.1排版风格 .22 4.2头文件 .26 4.3宏定义 .27 4.4变量与常量 .30 4.5条件判断 .32 4.6空间申请与释放 .33 4.7函数编写 .33 4.8类的编写 .37 4.9异常处理 .40 4.10特殊限制 .40 第五章第五章编译编译 .4141 第六章第六章esql/cesql/c 编码编码.4646 第二篇第二篇javajava 编码规范编码规范.4747 第一章第一章代

3、码组织代码组织 .4848 第二章第二章命名命名 .5151 2.1包命名 .51 2.2类命名 .51 2.3接口命名 .51 2.4方法命名 .51 2.5变量命名 .51 2.6类变量命名 .52 2.7常量命名 .52 2.8参数命名 .52 第三章第三章注释注释 .5353 3.1文档化注释 .53 3.2语句块注释 .57 3.3代码维护注释 .59 第四章第四章编码风格编码风格 .6161 4.1排版风格 .61 4.2包与类引用 .66 4.3变量与常量 .66 4.4类编写 .67 4.5方法编写 .68 4.6异常处理 .71 4.7特殊限制 .71 第五章第五章编译编译

4、.7373 第六章第六章jspjsp 编码编码.7474 6.1文件命名及存放位置 .74 6.2内容组织 .74 6.3编码风格 .76 6.4注释 .78 6.5缩进与对齐 .78 6.6表达式 .79 6.7javascript .79 第三篇第三篇powerbuilderpowerbuilder 编码规范编码规范.8080 第一章第一章代码组织代码组织 .8181 第二章第二章命名命名 .8282 2.1文件命名 .82 2.2对象命名 .82 2.3变量命名 .84 2.4常量命名 .85 2.5函数与事件命名 .85 2.6参数命名 .85 第三章第三章注释注释 .8585 3.1

5、文档化注释 .85 3.2语句块注释 .88 3.3代码维护注释 .88 第四章第四章编码风格编码风格 .8989 4.1界面风格 .89 4.2排版风格 .93 4.3变量与常量 .95 4.4条件判断 .96 4.5空间申请与释放 .97 4.6函数编写 .97 4.7特殊限制 .97 第五章第五章sqlsql 编码编码.9898 前前 言言 程序编码是一种艺术，既灵活又严谨，充满了创造性与奇思妙想。然而应用软件设计是一 项团结协作工程，而非程序员展示个人艺术的舞台，大型应用软件项目更是由很多程序员组成 的大型开发团队协同完成的。每个程序员都有自己的编码经验与风格，如果缺乏统一的编程规 范

6、，则可能导致软件产品最终程序代码风格迥异，可读性与可维护性均较差，不仅给程序代码 的理解带来障碍，也增加维护阶段的工作量。此外，经验证明不规范的编码行为往往还会导致 程序出现更多的隐含错误。 为规范编码行为，增强程序代码的可读性、可维护性，提高编码质量与效率，保障应用软 件产品整体品质与可持续开发性，特制定本规范。本规范分 c/c+编码规范、java 编码规范、 pb 编码规范三篇，分别从代码组织、命名、注释、编码风格、编译等方面加以阐述。规范文本 分为规则与建议两种，其中规则是强制执行的条款，建议则由程序员根据实际情况灵活掌握。 第一篇第一篇c/c+c/c+编码规范编码规范 第一章第一章代码

7、组织代码组织 规则规则 1: 1: 使用不同的文件分别放置模块的约束与实现。c+程序的约束文件使用.hpp 做扩展 名，实现文件使用.cpp 做扩展名；c 程序的约束文件使用.h 做扩展名，实现文件使用.c 做扩展 名。 规则规则 2: 2: 一个模块可以包含一个类或功能上紧密联系的多个类。禁止将功能关联松散的多 个类，放置到一个模块中。 规则规则 3: 3: 模块约束应仅包含模块对外提供的功能，禁止将模块内部使用的功能声明在模块 约束中。下例中 ischinesechar()是内部使用的函数，不提供给外部应用使用，因此不能在 commpub.hpp 中增加声明。 例：commpub.hpp

8、bool ischinesestring(const char* sinstr); 例：commpub.cpp staticstatic boolbool ischinesechar(constischinesechar(const char*char* s)s) ; bool ischinesestring(const char* sinstr) for(int ii = 0; ii strlen(sinstr); ii+) if(!ischinesechar(sinstr + ii) return false; return true; 规则规则 4: 4: 简单应用应创建下列目录结构，模

9、块程序代码应分别放置到 src/include 目录与 src/source 目录，编译文件放置到 src/source 目录，编译后的可执行文件放置到 rel/bin 目录， 静态库或动态库放置到 rel/lib 目录（应用使用的外部库及头文件放置在 rel 同级的 lib 与 lib/include 目录） 。 work directory src source makefile *.cpp *.c include *.hpp *.h rel bin lib 规则规则 5: 5: 复杂应用应分子系统创建目录结构，模块程序代码应分别放置到 src/module/include 目录与 src

10、/module/source 目录，应用编译文件放置到 src 目录，编译后 的可执行文件放置到 rel/bin 目录，静态库或动态库放置到 rel/lib 目录。 （应用使用的外部库 及头文件放置在 rel 同级的 lib 与 lib/include 目录） 规则规则 6: 6: 各子系统可以创建独立的编译文件并放置到 src/module/source 目录，编译后的 可执行文件放置到 rel/bin/module 目录或 rel/bin，静态库或动态库放置到 rel/lib/module 或 rel/lib 目录。此时，应创建一个编译全部子系统的编译文件或脚本放置到 src 目录。 wo

11、rk directory module1 source makefile *.cpp *.c include *.hpp *.h rel bin lib module2 source makefile *.cpp *.c include *.hpp *.h makefile|make.sh src module1 bin lib module2 bin lib 第二章第二章命名命名 规则规则 7: 7: 命名应遵循下列原则： 应简单清晰通俗； 应使用英文命名，禁止使用中文命名； 应尽量选择通用词汇； 应使用完整单词或词组，避免使用简称； 应准确表达其含义； 避免同时使用易混淆的字母与数字，如

12、1 与 l，0 与 o； 禁止使用只靠大小写区分的多个名称； 多单词组成的名称，单词的首字母应大写，如 filename。 规则规则 8: 8: 名称太长超过 15 字符时应使用简称。简称应遵循： 应使用标准的或常用的简写，如 temp（tmp） ，length（len） ； 应用范围内简写应一致且规范，避免各处简写各不相同； 简写可以使用单词的前一个或多个字母，如 channel（chan） 、connect（conn） ；也 可以使用去掉所有的不在词头的元音字母，如 screen（scrn） ，primtive（prmv） ； 多个单词组成的名称，使用有意义的单词或去掉无用的后缀并简称，如

13、 count of failure（failcnt） ，paging request（pagreq） 。 2.12.1文件命名文件命名 规则规则 9: 9: 文件命名应使用模块名的小写字母形式。禁止使用汉字或大、小写字母混用作为 代码文件名。 2.22.2变量命名变量命名 规则规则 10: 10: 变量命名主要采用匈牙利命名法，格式为作用域范围前缀_前缀基本类型名 称。其中，作用域范围前缀、前缀以小写字母表示且可选，基本类型以小写字母表示且必选。 常用前缀符常用前缀符 前缀符含义例子 g_ 全局变量g_stsystem, g_cmactype， g_strsysname s_ 静态变量s_nc

14、urcnt，s_strstaticname，s_psystime m_ 类数据成员m_nbanktype，m_swrkbuffer, m_strmyname h 句柄类变量hnfilehandle，hnsocket，hpprochandle p 指针类变量psreadbuff，pstrretstr，pptarget a 数组类变量anports，assendbuffers，apwrkbuffs 常用基本类型符常用基本类型符 前缀符含义例子 bbool bok，bquit，bfind c、ch char cflag，cbanktype，chsubsystemtype schar ssysname

15、，sstaticname，stimestr str cstring、string strsysname, strstaticname, strtimestr byunsign char bymacstr，bysendbuffer, bysrcbuffer n、i int ncnt，nport，nretcode llong lfilesize，loffset，lcount ddouble damount，dsumval，dwrkval ffloatfamount, fsumval, fwrkval ui/ulunsigned int/longuicnt, uifilesize, ulretcou

16、nt wword 与 unsigned int 等价的 32 位整数 dwdouble word 与 unsigned long 等价的 64 位整数 em 枚举型变量 emdays, emcolors, emset st 结构型编码stsystem，stctrldata, stset 规则规则 11: 11: 禁止使用单字母作为变量名。但下列常用单字母变量除外： 常用单字母变量常用单字母变量 变量类型说明 i,j,k,m,nint 循环变量 cchar 单字符变量 schar 字符数组变量 x,yint 位置变量 pchar* 指针变量 2.32.3常量与宏命名常量与宏命名 规则规则 12:

17、 12: 常量与宏应使用全大写名称，多词组名称使用_分隔各单词，并使用断行注释说明 其含义如： const int max_buff_size = 1024 / 最大存储区字节数 #define max_frame_size 512 / 单帧的最大长度 规则规则 13: 13: 作为错误码或返回码的宏，应使用 e_类型_name 形式，并使用断行注释说明其含 义。 #define e_file_notfound 61101001 / 文件不存在! #define e_db_select_fail 62301050 / 选取数据库失败! #define e_sys_invalid_status

18、62301001 / 系统状态非法! 规则规则 14: 14: 作为编译条件的宏，应使用_形式。如： #ifdef _none_throw_ #endif #ifndef _for_ccpc_ #endif 规则规则 15: 15: 为防止重复包含而定义的头文件预处理宏，应使用_name_hpp_（c+）或 _name_h_（c）形式，其中 name 为模块名称。如： #ifndef _csignal_hpp_ #define _csignal_hpp_ #endif #ifndef _csignal_h_ #define _csignal_h_ #endif 2.42.4类命名类命名 规则规

19、则 16: 16: 类命名应使用字符 c|t名称形式。其中名称应使用名词或名词短语，且每个单词 首字母大写。如：csignal，cfile，cstring，ctagmgr。 2.52.5函数命名函数命名 规则规则 17: 17: 函数命名应使用能够表达函数功能的英文动词或动宾结构短语，且每个单词的首 字母大写。如：getname()，strtrimleft()，killproc()。禁止在函数名称中使用非字母或数 字的其他字符，如下划线_。 建议建议 1: 1: 不应在函数名中使用数字，如：getname1()，kill2()。但数字是短语一部分的， 可以使用，如 killsigusr2()。

20、 2.62.6参数命名参数命名 建议建议 2: 2: 函数或方法的参数命名参考变量命名，但应使用 in，out、ret 等简写修饰参数， 增加函数声明的可读性。如： bool isspacestr(lpcstr sinstr, ulong nmaxlen = 0, ulong* plretoffset = null); void hextobin(lpcstr sinstr ,byte * psoutstr,ulong * plretsize = null); 第三章第三章注释注释 规则规则 18: 18: 程序代码中增加注释的目标是帮助对程序的阅读理解，不宜太多或太少，太多则 会对阅读产生干

21、扰，太少则不利于代码理解，因此只在必要的地方才加注释，且准确、易懂、 简洁。 3.13.1文档化注释文档化注释 3.1.13.1.1文件注释文件注释 规则规则 19: 19: 文件注释放置在文件头部，主要包括此文件的功能说明，编写人和修改人以及编 写和修改的日期，版权声明，版本等信息，应尽量使用中文。注释格式如下： /* * file filename.hppfilename.hpp * brief 文件简要说明文件简要说明 * * 文件详细说明文件详细说明 * * author * - 时间时间 作者作者 1 1 贡献贡献 1 1 * - 时间 作者 2 贡献 2 * - 时间 作者 3 贡

22、献 3 * * version * - 时间时间 版本版本 1 1 简要版本说明简要版本说明 1 1 * - 时间 版本 2 简要版本说明 2 * * par 其他重要信息： * 其他重要信息说明 * * warning 警告信息 * * par 版权信息： * 版本声明信息版本声明信息 */ 例： /* * file csignal.hpp * brief unix 信号函数封装类 * * 本类封装部分 unix 信号处理函数，简化在 unix 下编写信号处理程序的编码难度。 * 本类主要提供下列三类方法： * - 信号集合管理，提供信号集合的添加、删除、判断功能； * - 信号句柄管理，提

23、供设置与获取信号处理函数功能； * - 信号处理，设置与获取阻塞信号集、发送信号、等待信号功能。 * * author * - 2007-03-05 lny 创建初始版本 * - 2007-03-07 lny 添加文档注释信息 * version * - 2007-03-05 v1.0 创建初始版本 * - 2007-03-07 v2.0 添加文档注释信息 * * warning 本类不能在 win32 操作系统使用。 * * par 版权信息： * copyright(c)copyright(c) 2007-20072007-2007 cncc/cdccncc/cdc */ 注：粗体字为需定

24、制化的内容；兰色字为可选的内容，如果没有这些内容，请删除。下同。 3.1.23.1.2类注释类注释 规则规则 20: 20: 类注释放置在类声明前，主要介绍类的功能及相关说明。注释格式如下： /* * brief 类简要说明类简要说明 * * 类详细说明类详细说明 * * par 其他重要信息 * 其他重要信息说明 * * par 变更历史： * - 时间 作者 修改说明 */ 例： /* * brief unix 信号处理函数封装类 * * 本类封装部分 unix 信号处理函数，简化在 unix 下编写信号处理程序的编码难度。 * 本类主要提供下列三类方法： * - 信号集合管理，提供信号集

25、合的添加、删除、判断功能； * - 信号句柄管理，提供设置与获取信号处理函数功能； * - 信号处理，设置与获取阻塞信号集、发送信号、等待信号功能。 * * warning 本类不能在 win32 操作系统使用。 */ class csignal 3.1.33.1.3函数或方法注释函数或方法注释 规则规则 21: 21: 函数或方法注释放置在其声明前，主要介绍函数的功能、参数、返回值、异常、 使用说明、范例、引用关系、变更信息等信息。注释格式如下： /* * brief 函数功能简要说明函数功能简要说明 * param in|out 参数名称 1 参数 1 简要说明； * param in|o

26、ut 参数名称 2 参数 2 简要说明。 * return 返回值说明 * - 返回值 1 返回值 1 说明； * - 返回值 2 返回值 2 说明。 * exception 异常说明 * - 异常 1 异常 1 说明； * - 异常 2 异常 2 说明。 * * note 函数功能详细说明。 * - 详细说明 1； * - 详细说明 2。 * warning 警告信息 * deprecated 函数即将失效警告 * see 引用说明 * * par 使用范例: * code * 例子程序 * endcode * * par 算法或流程说明: * 详细算法或流程说明 * * par 变更历史：

27、 * - 时间 作者 修改说明 */ 例： /* * brief 添加一个或多个信号到信号集合。 * param out stset 要操作的信号集合； * param in nsignal 要添加到集合的信号； * param in nothersignal 要添加到集合的其他信号。 * return 添加失败返回负整数，失败原因可以从 errno 获取。 * note 如果要添加多个信号，则必须使用 0 作为最后一个信号。 * warning 如果添加多个信号时没有使用 0 作结束，则程序可能异常中止！ * see delfromset()、addalltoset()、clearset()

28、 * * par 使用范例: * code * int nretcode = sig.addtoset( * if(nretcode 0) .fail . * . * nretcode = sig.addtoset( * if(nretcode 0) .fail . * endcode */ int addtoset(sigset_t* stset, int nsignal, int nothersignal = 0, .); 建议建议 3: 3: 重要的或复杂的函数，应提供算法说明或使用范例。如： 例： /* * brief 根据行号与密码生成报尾校验码作为身份认证串。 * param in

29、 sbankcode 行号； * param in spassword 密码。 * return 身份认证串。 * par 算法介绍： * -# 计算 sbankcode + spassword 的 md5 数字摘要，输出 32 位字符； * -# 取 32 位字符的 0，5，10，15，16，21，26，31 位作 16 位字符串的偶数位； * -# 取authbeps各位作 16 位字符串的奇数位； * -# 加密这 16 位的字符串，得到 32 位的字符串作为认证串。 */ cstring buildauthstr(lpcstr sbankcode, lpcstr spassword);

30、 3.1.43.1.4数据成员注释数据成员注释 规则规则 22: 22: 类的每个数据成员均使用断行注释。注释格式如下： 例： class cmtmsg private: bool m_bbodyinfile;/ 是文件型报文？ cstring m_strfilename;/ 文件型报文的文件名 cstring m_strbody;/ 直接设置的报体串 cmtmsgheader m_header;/ 报头对象 cmtmsgtail m_tail;/ 报尾对象 cmtbatheader m_batheader;/ 批量业务头对象 3.1.53.1.5结构注释结构注释 规则规则 23: 23: 结

31、构可使用简单注释，也可使用与类相同的注释格式，其数据成员使用断行注释。 注释格式如下： 例： /* 报头结构，总长度 138 字节。*/ struct cmtheadermap char blockmark3;/ 报头块前缀 = 1:。 char verid1;/ 版本号，保留 = 0。 char mesglen6;/ 报文总长度，保留，目前为空白。 char apptradecode8;/ 业务码 0 位(系统号) 1-3 位 cmt 号 4 位 节点 5-7 位 保留。 char startaddr12;/ 报文源地址，即报文发起人。 char destaddr12;/ 报文目标地址，即报

32、文接收人。 char mesgpurp1;/ 报文用途，保留。 char outform1;/ 输出标识，保留。 char mesgidmsgid_len;/ 报文标识号，报文发起人生成，通信层唯一确定 一个报文。 char mesgreqnorequestid_len; / 报文参考号，报文发起人生成，回应报文带 回进行报文匹配。 char workdate8;/ 报文日期，格式为 yyyymmdd。 char senttime14;/ 报文时间，格式为 yyyymmddhhmiss。 char exptime4;/ 报文有效期，保留，0-0 xffff=65535。 char deliti

33、me6;/ 报文提交时间，保留，格式为 hhmiss。 char mesgpri1;/ 报文优先级，0 x0-0 xf=15。 char reserve20;/ 保留域。 char finalmark1;/ 报头块后缀 = 。 ; 3.1.63.1.6宏与变量注释宏与变量注释 规则规则 24: 24: 宏与变量使用简单注释或断行注释。特别重要的宏可以使用与类相同的文档注释。 注释格式如下： 例： #define mbt_prefix / 报文块开始标志 #define mbt_suffix / 报文块结束标志 #define mbt_header 1: / 报头块开始标志 #define mb

34、t_businessheader 2: / 业务头块开始标志 #define mbt_businessdata 3: / 正文块开始标志 #define mbt_tail c: / 报尾块开始标志 #define mbt_file f: / 文件说明块开始标志 #define mbt_batheader b: / 批量信息块开始标志 #define tag_prefix : / tag 名开始标志 #define tag_suffix : / tag 名结束标志 #define msgid_len 20 / 报文标识号长度(msgid) #define requestid_len 20 / 报

35、文参考号长度(reqid) 例： /* 业务头保留域长度 */ #define cmtbh_reserved_len 16 例： /* * brief 短报文正文体最大长度。 * * 此长度应根据 mqcmt 类定义最大消息长度进行调整，超过此长度的报文应分为多个报 文片断传输。 * * par 计算公式： * code * 最大长度 = mqcmt 消息长度 - sizeof(cmtmsgheader) - sizeof(cmtmsgtail) - sizeof(mqmsg) +1 * = mqcmt 最大消息长度 - 175 * endcode * 目前，mqcmt 类定义的最大消息长度为

36、 1m=1048576 字节。 */ #define short_msgbody_max_len 1000000 3.1.73.1.7文档注释技巧文档注释技巧 建议建议 4: 4: 为使 doxygen 工具能生成更好的文档，编写文档注释时参考下列技巧： 注释中使用的标识符前后均应留一个空格，以便 doxygen 识别此标识符，并自动生成 一个引用连接。如： /* * * par cmt 报文格式说明： * - cmt 报文由报头( cmtmsgheader )、可选的批量业务头( cmtbatheader )、正文 体、报尾( cmtmsgtail )组成。其中除正文体外，其余各块都是定长的

37、； * - 正文体由一个或多个业务块组成。每个业务块由一个定长的业务头( cmtbusinessheader )与一个变长正文块( cmtbusinessdata )组成； * - 正文块( cmtbusinessdata )由一个或多个 tag 码:tag 值对(报文域)组成，部分 tag 值又可由多个定长子域组成； * - 正文体可放置在报文中，也可存储在文件中，而在报文中仅放置文件名； * - 当正文体在文件中，则说明批量业务头、业务头、正文块存储在文件中。 */ 注释中可使用 html 标记美化最终文档，但别滥用美化标记； 较长的文档注释需要分段说明时，使用分段。如果需要段首缩进两字符

38、，使用全 角的空格。 文档注释中可以使用par 增加一个小节，灵活使用此标记可以任意地扩展文档的结构， 满足特殊描述的需要。如： /* * * * par 算法原理： * 计算机内部运算使用的基数是 2，即满 2 进位。如果计算机字长为 32 位，则最大 可以表示的整数为 4294967296. * 为了突破计算机最大整数的限制，可以采取两种做法，一是扩大基数，二是增加字 长。 * 根据此原理，本类使用 65536 作为基数，每个整数的最大位数 10(unsigned int array 10)， * 因此可以最大整数是 65536 的 10 次方，约 1.4e48。通过变更基数或位数，本类理

39、 论上可以处理的任意整数。 */ 需要生成圆点列表时使用，需要生成编号列表时使用#。 需要特别说明一段文字，可以使用 code/endcode。如： * par 计算公式： * code * 最大长度 = mqcmt 消息长度 - sizeof(cmtmsgheader) - sizeof(cmtmsgtail) - sizeof(mqmsg) +1 * = mqcmt 最大消息长度 - 175 * endcode 为使 doxygen 正确生成函数或方法的连接，注释中的函数名或方法名前后应留一个空 格。如该函数或方法没有重载，则不必使用参数列表，如 gettag()。如该函数或方法 重载，则应必须使用参数（类型）列表，如 gettag(lpcstr, amount return; / 清除行计数 static int nlinechars = 0; / 输出的行长度计数 if(bresetlinechars) / 行计数复位 nlinechars = 0; / 计算输出长度 int no