《软件编码规范方案.doc》由会员分享，可在线阅读，更多相关《软件编码规范方案.doc（97页珍藏版）》请在三一办公上搜索。
1、软件编码规范文件状态： 草稿 正式发布 正在修改文件编号：RDC-DED-SCS-SPC-00当前版本：作 者：审 核 人：完成日期：中国人民银行清算总中心支付系统开发中心文档修订记录版本编号变化状态简要说明日期变更人批准日期批准人注：变化状态：A增加，M修改，D删除 目 录第一篇C/C+编码规范6第一章代码组织6第二章命名92.1文件命名92.2变量命名92.3常量与宏命名102.4类命名102.5函数命名102.6参数命名11第三章注释123.1文档化注释123.2语句块注释173.3代码维护注释20第四章编码风格224.1排版风格224.2头文件264.3宏定义274.4变量与常量304
2、.5条件判断324.6空间申请与释放334.7函数编写334.8类的编写374.9异常处理404.10特殊限制40第五章编译41第六章ESQL/C编码46第二篇JAVA编码规范47第一章代码组织48第二章命名512.1包命名512.2类命名512.3接口命名512.4方法命名512.5变量命名512.6类变量命名522.7常量命名522.8参数命名52第三章注释533.1文档化注释533.2语句块注释573.3代码维护注释59第四章编码风格614.1排版风格614.2包与类引用664.3变量与常量664.4类编写674.5方法编写684.6异常处理714.7特殊限制71第五章编译73第六章JS
3、P编码746.1文件命名及存放位置746.2内容组织746.3编码风格766.4注释786.5缩进与对齐786.6表达式796.7JavaScript79第三篇POWERBUILDER编码规范80第一章代码组织81第二章命名822.1文件命名822.2对象命名822.3变量命名842.4常量命名852.5函数与事件命名852.6参数命名85第三章注释853.1文档化注释853.2语句块注释883.3代码维护注释88第四章编码风格894.1界面风格894.2排版风格934.3变量与常量954.4条件判断964.5空间申请与释放974.6函数编写974.7特殊限制97第五章SQL编码98前 言程序
4、编码是一种艺术，既灵活又严谨，充满了创造性与奇思妙想。然而应用软件设计是一项团结协作工程，而非程序员展示个人艺术的舞台，大型应用软件项目更是由很多程序员组成的大型开发团队协同完成的。每个程序员都有自己的编码经验与风格，如果缺乏统一的编程规范，则可能导致软件产品最终程序代码风格迥异，可读性与可维护性均较差，不仅给程序代码的理解带来障碍，也增加维护阶段的工作量。此外，经验证明不规范的编码行为往往还会导致程序出现更多的隐含错误。为规范编码行为，增强程序代码的可读性、可维护性，提高编码质量与效率，保障应用软件产品整体品质与可持续开发性，特制定本规范。本规范分C/C+编码规范、Java编码规范、PB编码
5、规范三篇，分别从代码组织、命名、注释、编码风格、编译等方面加以阐述。规范文本分为规则与建议两种，其中规则是强制执行的条款，建议则由程序员根据实际情况灵活掌握。第一篇 C/C+编码规范第一章 代码组织规则1: 使用不同的文件分别放置模块的约束与实现。C+程序的约束文件使用.hpp做扩展名，实现文件使用.cpp做扩展名；C程序的约束文件使用.h做扩展名，实现文件使用.c做扩展名。规则2: 一个模块可以包含一个类或功能上紧密联系的多个类。禁止将功能关联松散的多个类，放置到一个模块中。规则3: 模块约束应仅包含模块对外提供的功能，禁止将模块内部使用的功能声明在模块约束中。下例中IsChineseCha
6、r()是内部使用的函数，不提供给外部应用使用，因此不能在commpub.hpp中增加声明。例：commpub.hppBOOL IsChineseString(const char* sInStr);例：commpub.cppstatic BOOL IsChineseChar(const char* s) ;BOOL IsChineseString(const char* sInStr)for(int ii = 0; ii strlen(sInStr); ii+) if(!IsChineseChar(sInStr + ii) return FALSE; return TRUE;规则4: 简单应用
7、应创建下列目录结构，模块程序代码应分别放置到src/include目录与src/source目录，编译文件放置到src/source目录，编译后的可执行文件放置到rel/bin目录，静态库或动态库放置到rel/lib目录（应用使用的外部库及头文件放置在rel同级的lib与lib/include目录）。规则5: 复杂应用应分子系统创建目录结构，模块程序代码应分别放置到src/module/include目录与src/module/source目录，应用编译文件放置到src目录，编译后的可执行文件放置到rel/bin目录，静态库或动态库放置到rel/lib目录。（应用使用的外部库及头文件放置在re
8、l同级的lib与lib/include目录）规则6: 各子系统可以创建独立的编译文件并放置到src/module/source目录，编译后的可执行文件放置到rel/bin/module目录或rel/bin，静态库或动态库放置到rel/lib/module或rel/lib目录。此时，应创建一个编译全部子系统的编译文件或脚本放置到src目录。第二章 命名规则7: 命名应遵循下列原则：l 应简单清晰通俗；l 应使用英文命名，禁止使用中文命名；l 应尽量选择通用词汇；l 应使用完整单词或词组，避免使用简称；l 应准确表达其含义；l 避免同时使用易混淆的字母与数字，如1与l，0与o；l 禁止使用只靠大小
9、写区分的多个名称；l 多单词组成的名称，单词的首字母应大写，如FileName。规则8: 名称太长超过15字符时应使用简称。简称应遵循：l 应使用标准的或常用的简写，如Temp（tmp），Length（len）；l 应用范围内简写应一致且规范，避免各处简写各不相同；l 简写可以使用单词的前一个或多个字母，如Channel（Chan）、Connect（Conn）；也可以使用去掉所有的不在词头的元音字母，如screen（scrn），primtive（prmv）；l 多个单词组成的名称，使用有意义的单词或去掉无用的后缀并简称，如Count of Failure（FailCnt），Paging Req
10、uest（PagReq）。2.1 文件命名规则9: 文件命名应使用模块名的小写字母形式。禁止使用汉字或大、小写字母混用作为代码文件名。2.2 变量命名规则10: 变量命名主要采用匈牙利命名法，格式为作用域范围前缀_前缀基本类型名称。其中，作用域范围前缀、前缀以小写字母表示且可选，基本类型以小写字母表示且必选。常用前缀符前缀符含义例子g_全局变量g_stSystem, g_cMacType， g_strSysNames_静态变量s_nCurCnt，s_strStaticName，s_pSysTimem_类数据成员m_nBankType，m_sWrkBuffer, m_strMyNameh句柄类变
11、量hnFileHandle，hnSocket，hpProcHandlep指针类变量psReadBuff，pstrRetStr，ppTargeta数组类变量anPorts，asSendBuffers，apWrkBuffs常用基本类型符前缀符含义例子bboolbOK，bQuit，bFindc、chcharcFlag，cBankType，chSubSystemTypeschar sSysName，sStaticName，sTimeStrstrCString、StringstrSysName, strStaticName, strTimeStrbyunsign char byMacStr，bySend
12、Buffer, bySrcBuffern、iintnCnt，nPort，nRetCodellonglFileSize，lOffset，lCountddoubledAmount，dSumVal，dWrkValffloatfAmount, fSumVal, fWrkValui/ulunsigned int/longuiCnt, uiFileSize, ulRetCountwWORD与unsigned int等价的32位整数dwDOUBLE WORD与unsigned long等价的64位整数em枚举型变量emDays, emColors, emSetst结构型编码stSystem，stCtrlDa
13、ta, stSet规则11: 禁止使用单字母作为变量名。但下列常用单字母变量除外：常用单字母变量变量类型说明i,j,k,m,nint循环变量cchar 单字符变量schar 字符数组变量x,yint位置变量pchar*指针变量2.3 常量与宏命名规则12: 常量与宏应使用全大写名称，多词组名称使用_分隔各单词，并使用断行注释说明其含义如：const int MAX_BUFF_SIZE = 1024 / 最大存储区字节数#define MAX_FRAME_SIZE 512 / 单帧的最大长度规则13: 作为错误码或返回码的宏，应使用E_类型_NAME形式，并使用断行注释说明其含义。#define
14、 E_FILE_NOTFOUND 61101001 / 文件不存在!#define E_DB_SELECT_FAIL 62301050 / 选取数据库失败!#define E_SYS_INVALID_STATUS 62301001 / 系统状态非法!规则14: 作为编译条件的宏，应使用_形式。如：#ifdef _NONE_THROW_#endif#ifndef _FOR_CCPC_#endif规则15: 为防止重复包含而定义的头文件预处理宏，应使用_NAME_HPP_（C+）或_NAME_H_（C）形式，其中NAME为模块名称。如：#ifndef _CSIGNAL_HPP_#define _C
15、SIGNAL_HPP_#endif#ifndef _CSIGNAL_H_#define _CSIGNAL_H_#endif2.4 类命名规则16: 类命名应使用字符C|T名称形式。其中名称应使用名词或名词短语，且每个单词首字母大写。如：CSignal，CFile，CString，CTagMgr。2.5 函数命名规则17: 函数命名应使用能够表达函数功能的英文动词或动宾结构短语，且每个单词的首字母大写。如：GetName()，StrTrimLeft()，KillProc()。禁止在函数名称中使用非字母或数字的其他字符，如下划线_。建议1: 不应在函数名中使用数字，如：GetName1()，Kil
16、l2()。但数字是短语一部分的，可以使用，如KillSigusr2()。2.6 参数命名建议2: 函数或方法的参数命名参考变量命名，但应使用In，Out、Ret等简写修饰参数，增加函数声明的可读性。如：BOOL IsSpaceStr(LPCSTR sInStr, ULONG nMaxLen = 0, ULONG* plRetOffset = NULL);void HexToBin(LPCSTR sInStr ,BYTE * psOutStr,ULONG * plRetSize = NULL);第三章 注释规则18: 程序代码中增加注释的目标是帮助对程序的阅读理解，不宜太多或太少，太多则会对阅读
17、产生干扰，太少则不利于代码理解，因此只在必要的地方才加注释，且准确、易懂、简洁。3.1 文档化注释3.1.1 文件注释规则19: 文件注释放置在文件头部，主要包括此文件的功能说明，编写人和修改人以及编写和修改的日期，版权声明，版本等信息，应尽量使用中文。注释格式如下：/* * file filename.hpp * brief 文件简要说明 * * 文件详细说明 * * author * - 时间 作者1 贡献1 * - 时间 作者2 贡献2* - 时间 作者3 贡献3* version* - 时间 版本1 简要版本说明1* - 时间 版本2 简要版本说明2* par 其他重要信息：* 其他重
18、要信息说明* * warning 警告信息* * par 版权信息：* 版本声明信息 */例：/* * file csignal.hpp * brief UNIX 信号函数封装类 * * 本类封装部分UNIX信号处理函数，简化在UNIX下编写信号处理程序的编码难度。 * 本类主要提供下列三类方法： * - 信号集合管理，提供信号集合的添加、删除、判断功能； * - 信号句柄管理，提供设置与获取信号处理函数功能； * - 信号处理，设置与获取阻塞信号集、发送信号、等待信号功能。 * author * - 2007-03-05 lny 创建初始版本 * - 2007-03-07 lny 添加文档注
19、释信息 * version* - 2007-03-05 V1.0 创建初始版本 * - 2007-03-07 V2.0 添加文档注释信息 * warning 本类不能在WIN32操作系统使用。* par 版权信息：* Copyright(C) 2007-2007 CNCC/CDC*/注：粗体字为需定制化的内容；兰色字为可选的内容，如果没有这些内容，请删除。下同。3.1.2 类注释规则20: 类注释放置在类声明前，主要介绍类的功能及相关说明。注释格式如下：/* * brief 类简要说明 * * 类详细说明 * * par 其他重要信息* 其他重要信息说明* par 变更历史： * - 时间 作
20、者 修改说明*/例：/* * brief UNIX信号处理函数封装类 * * 本类封装部分UNIX信号处理函数，简化在UNIX下编写信号处理程序的编码难度。 * 本类主要提供下列三类方法： * - 信号集合管理，提供信号集合的添加、删除、判断功能； * - 信号句柄管理，提供设置与获取信号处理函数功能； * - 信号处理，设置与获取阻塞信号集、发送信号、等待信号功能。 * * warning 本类不能在WIN32操作系统使用。 */class CSignal 3.1.3 函数或方法注释规则21: 函数或方法注释放置在其声明前，主要介绍函数的功能、参数、返回值、异常、使用说明、范例、引用关系、变
21、更信息等信息。注释格式如下：/* * brief 函数功能简要说明 * param in|out 参数名称1 参数1简要说明；* param in|out 参数名称2 参数2简要说明。 * return 返回值说明 * - 返回值1 返回值1说明； * - 返回值2 返回值2说明。 * exception 异常说明* - 异常1 异常1说明； * - 异常2 异常2说明。 * * note 函数功能详细说明。 * - 详细说明1； * - 详细说明2。 * warning 警告信息* deprecated 函数即将失效警告* see 引用说明 * * par 使用范例: * code * 例子
22、程序 * endcode * par 算法或流程说明:* 详细算法或流程说明* * par 变更历史： * - 时间 作者 修改说明 */例：/* * brief 添加一个或多个信号到信号集合。 * param out stSet 要操作的信号集合； * param in nSignal 要添加到集合的信号； * param in nOtherSignal 要添加到集合的其他信号。 * return 添加失败返回负整数，失败原因可以从errno获取。 * note如果要添加多个信号，则必须使用0作为最后一个信号。 * warning 如果添加多个信号时没有使用0作结束，则程序可能异常中止！ *
23、 see DelFromSet()、AddAllToSet()、ClearSet() * * par使用范例: * code * int nRetCode = sig.AddToSet(&stSet, SIGUSR1, SIGUSR2, 0); * if(nRetCode 0) .Fail . * . * nRetCode = sig.AddToSet(&stSet, SIGHUP); * if(nRetCode 0) .Fail . * endcode */ int AddToSet(sigset_t* stSet, int nSignal, int nOtherSignal = 0, .)
24、;建议3: 重要的或复杂的函数，应提供算法说明或使用范例。如：例：/* * brief 根据行号与密码生成报尾校验码作为身份认证串。 * param in sBankCode 行号； * param in sPassword 密码。 * return 身份认证串。 * par 算法介绍： * -# 计算 sBankCode + sPassword 的MD5数字摘要，输出32位字符； * -# 取32位字符的0，5，10，15，16，21，26，31位作16位字符串的偶数位； * -# 取AUTHBEPS各位作16位字符串的奇数位； * -# 加密这16位的字符串，得到32位的字符串作为认证串。
25、 */CString BuildAuthStr(LPCSTR sBankCode, LPCSTR sPassword);3.1.4 数据成员注释规则22: 类的每个数据成员均使用断行注释。注释格式如下：例：class CMTMsgprivate: BOOL m_bBodyInFile;/ 是文件型报文？ CString m_strFileName;/ 文件型报文的文件名 CString m_strBody;/ 直接设置的报体串 CMTMsgHeader m_Header;/ 报头对象 CMTMsgTail m_Tail;/ 报尾对象 CMTBatHeader m_BatHeader;/ 批量业
26、务头对象3.1.5 结构注释规则23: 结构可使用简单注释，也可使用与类相同的注释格式，其数据成员使用断行注释。注释格式如下：例：/* 报头结构，总长度 138 字节。*/struct CMTHeaderMap char blockMark3;/ 报头块前缀 = 1:。 char verID1;/ 版本号，保留 = 0。 char mesgLen6;/ 报文总长度，保留，目前为空白。 char appTradeCode8;/ 业务码 0位(系统号) 1-3位 CMT号 4位 节点 5-7位 保留。 char startAddr12;/ 报文源地址，即报文发起人。 char destAddr12
27、;/ 报文目标地址，即报文接收人。 char mesgPurp1;/ 报文用途，保留。 char outForm1;/ 输出标识，保留。 char mesgIDMSGID_LEN;/ 报文标识号，报文发起人生成，通信层唯一确定一个报文。 char mesgReqNoREQUESTID_LEN; / 报文参考号，报文发起人生成，回应报文带回进行报文匹配。 char workDate8;/ 报文日期，格式为YYYYMMDD。 char sentTime14;/ 报文时间，格式为YYYYMMDDHHMISS。 char expTime4;/ 报文有效期，保留，0-0xFFFF=65535。 char
28、 deliTime6;/ 报文提交时间，保留，格式为HHMISS。 char mesgPRI1;/ 报文优先级，0x0-0xF=15。 char reserve20;/ 保留域。 char finalMark1;/ 报头块后缀 = 。;3.1.6 宏与变量注释规则24: 宏与变量使用简单注释或断行注释。特别重要的宏可以使用与类相同的文档注释。注释格式如下：例：#define MBT_PREFIX / 报文块开始标志#define MBT_SUFFIX / 报文块结束标志#define MBT_HEADER 1: / 报头块开始标志#define MBT_BUSINESSHEADER 2: /
29、业务头块开始标志#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 / 报文参考号长度(REQID)例：/* 业务头保留域长度 */#de
30、fine CMTBH_RESERVED_LEN 16例：/* * brief 短报文正文体最大长度。* * 此长度应根据 MQCMT 类定义最大消息长度进行调整，超过此长度的报文应分为多个报文片断传输。 * * par计算公式： * code * 最大长度 = MQCMT消息长度 - sizeof(CMTMsgHeader) - sizeof(CMTMsgTail) - sizeof(MQMsg) +1 * = MQCMT最大消息长度 - 175 * endcode * 目前，MQCMT 类定义的最大消息长度为 1M=1048576 字节。 */#define SHORT_MSGBODY_MA
31、X_LEN 10000003.1.7 文档注释技巧建议4: 为使doxygen工具能生成更好的文档，编写文档注释时参考下列技巧：l 注释中使用的标识符前后均应留一个空格，以便doxygen识别此标识符，并自动生成一个引用连接。如：/* * * par CMT报文格式说明： * - CMT报文由报头( CMTMsgHeader )、可选的批量业务头( CMTBatHeader )、正文体、报尾( CMTMsgTail )组成。其中除正文体外，其余各块都是定长的； * - 正文体由一个或多个业务块组成。每个业务块由一个定长的业务头( CMTBusinessHeader )与一个变长正文块( CMT
32、BusinessData )组成； * - 正文块( CMTBusinessData )由一个或多个TAG码:TAG值对(报文域)组成，部分TAG值又可由多个定长子域组成； * - 正文体可放置在报文中，也可存储在文件中，而在报文中仅放置文件名； * - 当正文体在文件中，则说明批量业务头、业务头、正文块存储在文件中。 */l 注释中可使用HTML标记美化最终文档，但别滥用美化标记；l 较长的文档注释需要分段说明时，使用分段。如果需要段首缩进两字符，使用全角的空格。l 文档注释中可以使用par增加一个小节，灵活使用此标记可以任意地扩展文档的结构，满足特殊描述的需要。如：/* * * * par
33、 算法原理： * 计算机内部运算使用的基数是2，即满2进位。如果计算机字长为32位，则最大可以表示的整数为4294967296. * 为了突破计算机最大整数的限制，可以采取两种做法，一是扩大基数，二是增加字长。 * 根据此原理，本类使用65536作为基数，每个整数的最大位数10(unsigned int array 10)， * 因此可以最大整数是65536的10次方，约1.4e48。通过变更基数或位数，本类理论上可以处理的任意整数。*/l 需要生成圆点列表时使用，需要生成编号列表时使用#。l 需要特别说明一段文字，可以使用 code/endcode。如：* par计算公式： * code *
34、 最大长度 = MQCMT消息长度 - sizeof(CMTMsgHeader) - sizeof(CMTMsgTail) - sizeof(MQMsg) +1 * = MQCMT最大消息长度 - 175 * endcodel 为使doxygen正确生成函数或方法的连接，注释中的函数名或方法名前后应留一个空格。如该函数或方法没有重载，则不必使用参数列表，如 GetTag()。如该函数或方法重载，则应必须使用参数（类型）列表，如GetTag(LPCSTR, AMOUNT&, BOOL, int, int)。3.2 语句块注释规则25: 程序代码主要流程、重要算法以及逻辑性较强的代码和有特殊设计意
35、图的代码（如没有break的case块、空循环体、空语句块）等位置，应添加语句块注释。通过语句块注释，应能反映程序功能的概貌，注释量不应少于该模块概要设计的流程描述量。规则26: 语句块注释应遵循下列原则：l 应使用断行注释，即/；l 一目了然的语句不应注释；l 每个分支、每个功能段均应注释；l 应放置在紧临该语句块上方或语句右侧，与其上方的语句块应留一空行，禁止放置在语句块的下方，但可以在语句块下方放置该语句块结束的注释。放置在语句右侧的注释垂直方向尽量对齐，缩进位置与语句块相同。例：主要流程注释/ 参数检查 if(nInpLen = 0 | byInpData = NULL) / 检查失败
36、strOutStr.Empty();return; / 清除行计数 static int nLineChars = 0; / 输出的行长度计数 if(bResetLineChars) / 行计数复位 nLineChars = 0; / 计算输出长度 int nOutLen = 2*4*(nInpLen/3 +1); / 考虑到要添加回车换行，多分配点空间 char * p = strOutStr.GetBufferSetLength(nOutLen); memset(p, 0, nOutLen);例：逻辑性较强 / 1.BankCode + Password CString strWrkStr
37、 = sWrkBankCode + sWrkPassword; / 2.计算MD5指纹 CString strMD5 = md5.HashBuffer(BYTE*)strWrkStr.GetBuffer(0), strWrkStr.GetLength(); / 3.选取八位数字指纹 char* p = strMD5.GetBuffer(0); char sTmpStr17; int ii=0; memset(sTmpStr, 0, sizeof(sTmpStr); for(ii=0; ii8; +ii) sTmpStr2*ii = p4*ii + ii%4; / 4.组合固定串 p = AUT
38、HBEPS; for(ii=0; ii8; +ii) sTmpStr2*ii+1 = pii;例：特殊设计意图BigInt:BigInt() / NOTHINGswitch(atoi(stCCSV0313_data.szOPERSTATUS) case 1: / 已付款 exec sql update CISCODT0702 set PAYCNT = :stCCSV0313_data.szCount where WORKDATE = :stCCSV0313_data.szWorkDate and CLSCODE = :stCCSV0313_data.szBankType and RSTYPE
39、= :stCCSV0313_data.szRSTYPE and ARSTSIGN = :stCCSV0313_data.szARSTSIGN and CGTYPE = :stCCSV0313_data.szCGTYPE; CheckDBError(CISCODT0702, E_DB_UPDATE); break; case 2: / 已退票 exec sql update CISCODT0702 set RTNCNT = :stCCSV0313_data.szCount where WORKDATE = :stCCSV0313_data.szWorkDate and CLSCODE = :st
40、CCSV0313_data.szBankType and RSTYPE = :stCCSV0313_data.szRSTYPE and ARSTSIGN = :stCCSV0313_data.szARSTSIGN and CGTYPE = :stCCSV0313_data.szCGTYPE; CheckDBError(CISCODT0702, E_DB_UPDATE); break; default: / DO NOTHING break;建议5: 需要注释一段代码时，避免使用/* */注释，而应使用#ifdef 0 #endif形式，因此这种形式可以嵌套。如：例：#ifdef 0/ 直接解析批量包报文（一次读取一个块）int CMTF
