软件编码规范doc文档格式.docx
《软件编码规范doc文档格式.docx》由会员分享，可在线阅读，更多相关《软件编码规范doc文档格式.docx（135页珍藏版）》请在冰豆网上搜索。
例：
commpub.hpp
BOOLIsChineseString（constchar*sInStr）;
commpub.cpp
staticBOOLIsChineseChar（constchar*s）
{
……;
}
BOOLIsChineseString（constchar*sInStr）
for（intii=0;
ii<
strlen（sInStr）;
ii++）
if（!
IsChineseChar（sInStr+ii））
{
returnFALSE;
}
returnTRUE;
规则4:
简单应用应创建下列目录结构，模块程序代码应分别放置到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目录。
（应用使用的外部库及头文件放置在rel同级的lib与lib/include目录）
规则6:
各子系统可以创建独立的编译文件并放置到src/module/source目录，编译后的可执行文件放置到rel/bin/module目录或rel/bin，静态库或动态库放置到rel/lib/module或rel/lib目录。
此时，应创建一个编译全部子系统的编译文件或脚本放置到src目录。
命名
规则7:
命名应遵循下列原则：
●应简单清晰通俗；
●应使用英文命名，禁止使用中文命名；
●应尽量选择通用词汇；
●应使用完整单词或词组，避免使用简称；
●应准确表达其含义；
●避免同时使用易混淆的字母与数字，如1与l，0与o；
●禁止使用只靠大小写区分的多个名称；
●多单词组成的名称，单词的首字母应大写，如FileName。
规则8:
名称太长超过15字符时应使用简称。
简称应遵循：
●应使用标准的或常用的简写，如Temp（tmp），Length（len）；
●应用范围内简写应一致且规范，避免各处简写各不相同；
●简写可以使用单词的前一个或多个字母，如Channel（Chan）、Connect（Conn）；
也可以使用去掉所有的不在词头的元音字母，如screen（scrn），primtive（prmv）；
●多个单词组成的名称，使用有意义的单词或去掉无用的后缀并简称，如CountofFailure（FailCnt），PagingRequest（PagReq）。
一.1文件命名
规则9:
文件命名应使用模块名的小写字母形式。
禁止使用汉字或大、小写字母混用作为代码文件名。
一.2变量命名
规则10:
变量命名主要采用匈牙利命名法，格式为[作用域范围前缀_][前缀]基本类型＋名称。
其中，作用域范围前缀、前缀以小写字母表示且可选，基本类型以小写字母表示且必选。
常用前缀符
前缀符
含义
例子
g_
全局变量
g_stSystem,g_cMacType，g_strSysName
s_
静态变量
s_nCurCnt，s_strStaticName，s_pSysTime
m_
类数据成员
m_nBankType，m_sWrkBuffer,m_strMyName
h
句柄类变量
hnFileHandle，hnSocket，hpProcHandle
p
指针类变量
psReadBuff，pstrRetStr，ppTarget
a
数组类变量
anPorts，asSendBuffers，apWrkBuffs
常用基本类型符
b
bool
bOK，bQuit，bFind
c、ch
char
cFlag，cBankType，chSubSystemType
s
char[]
sSysName，sStaticName，sTimeStr
str
CString、String
strSysName,strStaticName,strTimeStr
by
unsignchar[]
byMacStr，bySendBuffer,bySrcBuffer
n、i
int
nCnt，nPort，nRetCode
l
long
lFileSize，lOffset，lCount
d
double
dAmount，dSumVal，dWrkVal
f
float
fAmount,fSumVal,fWrkVal
ui/ul
unsignedint/long
uiCnt,uiFileSize,ulRetCount
w
WORD
与unsignedint等价的32位整数
dw
DOUBLEWORD
与unsignedlong等价的64位整数
em
枚举型变量
emDays,emColors,emSet
st
结构型编码
stSystem，stCtrlData,stSet
规则11:
禁止使用单字母作为变量名。
但下列常用单字母变量除外：
常用单字母变量
变量
类型
说明
i,j,k,m,n
循环变量
c
char
单字符变量
字符数组变量
x,y
位置变量
char*
指针变量
一.3常量与宏命名
规则12:
常量与宏应使用全大写名称，多词组名称使用_分隔各单词，并使用断行注释说明其含义如：
constintMAX_BUFF_SIZE=1024///<
最大存储区字节数
#defineMAX_FRAME_SIZE512///<
单帧的最大长度
规则13:
作为错误码或返回码的宏，应使用E_类型_NAME形式，并使用断行注释说明其含义。
#defineE_FILE_NOTFOUND61101001///<
文件不存在!
#defineE_DB_SELECT_FAIL62301050///<
选取数据库失败!
#defineE_SYS_INVALID_STATUS62301001///<
系统状态非法!
规则14:
作为编译条件的宏，应使用_<
NAME>
_形式。
如：
#ifdef_NONE_THROW_
#endif
…
#ifndef_FOR_CCPC_
规则15:
为防止重复包含而定义的头文件预处理宏，应使用__NAME_HPP__（C++）或__NAME_H__（C）形式，其中NAME为模块名称。
#ifndef__CSIGNAL_HPP__
#define__CSIGNAL_HPP__
#ifndef__CSIGNAL_H__
#define__CSIGNAL_H__
一.4类命名
规则16:
类命名应使用字符C|T＋名称形式。
其中名称应使用名词或名词短语，且每个单词首字母大写。
CSignal，CFile，CString，CTagMgr。
一.5函数命名
规则17:
函数命名应使用能够表达函数功能的英文动词或动宾结构短语，且每个单词的首字母大写。
GetName（），StrTrimLeft（），KillProc（）。
禁止在函数名称中使用非字母或数字的其他字符，如下划线_。
建议1:
不应在函数名中使用数字，如：
GetName1（），Kill2（）。
但数字是短语一部分的，可以使用，如KillSigusr2（）。
一.6参数命名
建议2:
函数或方法的参数命名参考变量命名，但应使用In，Out、Ret等简写修饰参数，增加函数声明的可读性。
BOOLIsSpaceStr（LPCSTRsInStr,ULONGnMaxLen=0,ULONG*plRetOffset=NULL）;
voidHexToBin（LPCSTRsInStr,BYTE*psOutStr,ULONG*plRetSize=NULL）;
注释
规则18:
程序代码中增加注释的目标是帮助对程序的阅读理解，不宜太多或太少，太多则会对阅读产生干扰，太少则不利于代码理解，因此只在必要的地方才加注释，且准确、易懂、简洁。
一.7文档化注释
一.7.1文件注释
规则19:
文件注释放置在文件头部，主要包括此文件的功能说明，编写人和修改人以及编写和修改的日期，版权声明，版本等信息，应尽量使用中文。
注释格式如下：
/**
*@filefilename.hpp
*@brief文件简要说明
*
*文件详细说明
*@author
*-时间作者1贡献1
*-时间作者2贡献2
*-时间作者3贡献3
*
*@version
*-时间版本1简要版本说明1
*-时间版本2简要版本说明2
*@par其他重要信息：
*其他重要信息说明
*
*@warning警告信息
*@par版权信息：
*版本声明信息
*/
*@filecsignal.hpp
*@briefUNIX信号函数封装类
*本类封装部分UNIX信号处理函数，简化在UNIX下编写信号处理程序的编码难度。
<
br>
*本类主要提供下列三类方法：
*-信号集合管理，提供信号集合的添加、删除、判断功能；
*-信号句柄管理，提供设置与获取信号处理函数功能；
*-信号处理，设置与获取阻塞信号集、发送信号、等待信号功能。
*@author
*-2007-03-05lny创建初始版本
*-2007-03-07lny添加文档注释信息
*@version
*-2007-03-05V1.0创建初始版本
*-2007-03-07V2.0添加文档注释信息
*@warning本类不能在WIN32操作系统使用。
*Copyright（C）2007-2007CNCC/CDC
*/
粗体字为需定制化的内容；
兰色字为可选的内容，如果没有这些内容，请删除。
下同。
一.7.2类注释
规则20:
类注释放置在类声明前，主要介绍类的功能及相关说明。
*@brief类简要说明
*类详细说明
*
*@par其他重要信息
*@par变更历史：
*-时间作者修改说明
*@briefUNIX信号处理函数封装类
*@warning本类不能在WIN32操作系统使用。
classCSignal
…
一.7.3函数或方法注释
规则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
*例子程序
*@endcode
*@par算法或流程说明:
*详细算法或流程说明
*@par变更历史：
*@brief添加一个或多个信号到信号集合。
*@param[out]stSet要操作的信号集合；
*@param[in]nSignal要添加到集合的信号；
*@param[in]nOtherSignal要添加到集合的其他信号。
*@return添加失败返回负整数，失败原因可以从errno获取。
*@note如果要添加多个信号，则必须使用0作为最后一个信号。
*@warning如果添加多个信号时没有使用0作结束，则程序可能异常中止！
*@seeDelFromSet（）、AddAllToSet（）、ClearSet（）
*@par使用范例:
*intnRetCode=sig.AddToSet（&
stSet,SIGUSR1,SIGUSR2,0）;
*if（nRetCode<
0）{...Fail...}
*...
*nRetCode=sig.AddToSet（&
stSet,SIGHUP）;
intAddToSet（sigset_t*stSet,intnSignal,intnOtherSignal=0,...）;
建议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位的字符串作为认证串。
CStringBuildAuthStr（LPCSTRsBankCode,LPCSTRsPassword）;
一.7.4数据成员注释
规则22:
类的每个数据成员均使用断行注释。
classCMTMsg
private:
BOOLm_bBodyInFile;
///<
是文件型报文？
CStringm_strFileName;
///<
文件型报文的文件名
CStringm_strBody;
直接设置的报体串
CMTMsgHeaderm_Header;
报头对象
CMTMsgTailm_Tail;
报尾对象
CMTBatHeaderm_BatHeader;
///<
批量业务头对象
一.7.5结构注释
规则23:
结构可使用简单注释，也可使用与类相同的注释格式，其数据成员使用断行注释。
/**报头结构，总长度138字节。
structCMTHeaderMap
charblockMark[3];
///<
报头块前缀={1:
。
charverID[1];
///<
版本号，保留=0。
charmesgLen[6];
报文总长度，保留，目前为空白。
charappTradeCode[8];
///<
业务码0位（系统号）1-3位CMT号4位节点5-7位保留。
charstartAddr[12];
报文源地址，即报文发起人。
chardestAddr[12];
报文目标地址，即报文接收人。
charmesgPurp[1];
报文用途，保留。
charoutForm[1];
输出标识，保留。
charmesgID[MSGID_LEN];
报文标识号，报文发起人生成，通信层唯一确定一个报文。
charmesgReqNo[REQUESTID_LEN];
///<
报文参考号，报文发起人生成，回应报文带回进行报文匹配。
charworkDate[8];
报文日期，格式为YYYYMMDD。
charsentTime[14];
报文时间，格式为YYYYMMDDHHMISS。
charexpTime[4];
报文有效期，保留，0-0xFFFF=65535。
chardeliTime[6];
报文提交时间，保留，格式为HHMISS。
charmesgPRI[1];
报文优先级，0x0-0xF=15。
charreserve[20];
保留域。
charfinalMark[1];
报头块后缀=}。
};
一.7.6宏与变量注释
规则24:
宏与变量使用简单注释或断行注释。
特别重要的宏可以使用与类相同的文档注释。
#defineMBT_PREFIX"
{"
报文块开始标志
#defineMBT_SUFFIX"
}"
报文块结束标志
#defineMBT_HEADER"
{1:
"
报头块开始标志
#defineMBT_BUSINESSHEADER"
{2:
业务头块开始标志
#defineMBT_BUSINESSDATA"
{3:
正文块开始标志
#defineMBT_TAIL"
{C:
报尾块开始标志
#defineMBT_FILE"
{F:
文件说明块开始标志
#defineMBT_BATHEADER"
{B:
批量信息块开始标志
#defineTAG_PREFIX"
:
TAG名开始标志
#defineTAG_SUFFIX"
TAG名结束标志
#defineMSGID_LEN20///<
报文标识号长度（MSGID）
#defineREQUESTID_LEN20///<
报文参考号长度（REQID）
/**业务头保留域长度*/
#defineCMTBH_RESERVED_LEN16
/**
*@brief短报文正文体最大长度。
*此长度应根据MQCMT类定义最大消息长度进行调整，超过此长度的报文应分为多个报文片断传输。
*@par计算公式：
*最大长度=MQCMT消息长度-sizeof（CMTMsgHeader）-sizeof（CMTMsgTail）-sizeof（MQMsg）+1
*=MQCMT最大消息长度-175
*目前，MQCMT类定义的最大消息长度为1M=1048576字节。
#defineSHORT_MSGBODY_MAX_LEN1000000
一.7.7文档注释技巧
建议4:
为使doxygen工具能生成更好的文档，编写文档注释时参考下列技巧：
●注释中使用的标识符前后均应留一个空格，以便doxygen识别此标识符，并自动生成一个引用连接。
*…
*@parCMT报文格式说明：
*-CMT报文由报头（CMTMsgHeader）、可选的批量业务头（CMTBatHeader）、正文体、报尾（CMTMsgTail）组成。
其中除正文体外，其余各块都是定长的；
*-正文体由一个或多个业务块组成。
每个业务块由一个定长的业务头（CMTBusinessHeader）与一个变长正文块（C
升级会员 