軟件編碼規(guī)范詳述(doc 98頁(yè)).doc

1、軟軟軟軟軟軟件件件件件件編編編編編編碼碼碼碼碼碼規(guī)規(guī)規(guī)規(guī)規(guī)規(guī)范范范范范范 文件編號(hào)：RDC-DED-SCS-SPC-00 當(dāng)前版本： 作 者： 審 核 人： 文件狀態(tài)： 草稿 正式發(fā)布 正在修改 完成日期： 中國(guó)人民銀行清算總中心 支付系統(tǒng)開(kāi)發(fā)中心 文檔修訂記錄 版本編號(hào)變化狀態(tài)簡(jiǎn)要說(shuō)明日期變更人批準(zhǔn)日期批準(zhǔn)人 注：變化狀態(tài)：A增加，M修改，D刪除 目目 錄錄 第一篇第一篇C/C+C/C+編碼規(guī)范編碼規(guī)范 .6 6 第一章第一章代碼組織代碼組織 .6 6 第二章第二章命名命名 .9 9 2.1文件命名 .9 2.2變量命名 .9 2.3常量與宏命名 .10 2.4類命名 .10 2.5函數(shù)命名

2、 .10 2.6參數(shù)命名 .11 第三章第三章注釋注釋 .1212 3.1文檔化注釋 .12 3.2語(yǔ)句塊注釋 .17 3.3代碼維護(hù)注釋 .20 第四章第四章編碼風(fēng)格編碼風(fēng)格 .2222 4.1排版風(fēng)格 .22 4.2頭文件 .26 4.3宏定義 .27 4.4變量與常量 .30 4.5條件判斷 .32 4.6空間申請(qǐng)與釋放 .33 4.7函數(shù)編寫 .33 4.8類的編寫 .37 4.9異常處理 .40 4.10特殊限制 .40 第五章第五章編譯編譯 .4141 第六章第六章ESQL/CESQL/C 編碼編碼.4646 第二篇第二篇JAVAJAVA 編碼規(guī)范編碼規(guī)范.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參數(shù)命名 .52 第三章第三章注釋注釋 .5353 3.1文檔化注釋 .53 3.2語(yǔ)句塊注釋 .57 3.3代碼維護(hù)注釋 .59 第四章第四章編碼風(fēng)格編碼風(fēng)格 .6161 4.1排版風(fēng)格 .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內(nèi)容組織 .74 6.3編碼風(fēng)格 .76 6.4注釋 .78 6.5縮進(jìn)與對(duì)齊 .78 6.6表達(dá)式 .79 6.7JavaScript .79 第三篇第三篇POWERBUILDERPOWERBUILDER 編碼規(guī)范編碼規(guī)范.8080 第一章第一章代碼組織代碼組織 .8181 第二章第二章命名命名 .8282 2.1文件命名 .82 2.2對(duì)象命名 .82 2.3變量命名 .84 2.4常量命名 .85 2.5函數(shù)與事件命名 .85 2.6參數(shù)命名 .85 第三章第三章注釋注釋 .8585 3.1

5、文檔化注釋 .85 3.2語(yǔ)句塊注釋 .88 3.3代碼維護(hù)注釋 .88 第四章第四章編碼風(fēng)格編碼風(fēng)格 .8989 4.1界面風(fēng)格 .89 4.2排版風(fēng)格 .93 4.3變量與常量 .95 4.4條件判斷 .96 4.5空間申請(qǐng)與釋放 .97 4.6函數(shù)編寫 .97 4.7特殊限制 .97 第五章第五章SQLSQL 編碼編碼.9898 前前 言言 程序編碼是一種藝術(shù)，既靈活又嚴(yán)謹(jǐn)，充滿了創(chuàng)造性與奇思妙想。然而應(yīng)用軟件設(shè)計(jì)是一 項(xiàng)團(tuán)結(jié)協(xié)作工程，而非程序員展示個(gè)人藝術(shù)的舞臺(tái)，大型應(yīng)用軟件項(xiàng)目更是由很多程序員組成 的大型開(kāi)發(fā)團(tuán)隊(duì)協(xié)同完成的。每個(gè)程序員都有自己的編碼經(jīng)驗(yàn)與風(fēng)格，如果缺乏統(tǒng)一的編程規(guī) 范

6、，則可能導(dǎo)致軟件產(chǎn)品最終程序代碼風(fēng)格迥異，可讀性與可維護(hù)性均較差，不僅給程序代碼 的理解帶來(lái)障礙，也增加維護(hù)階段的工作量。此外，經(jīng)驗(yàn)證明不規(guī)范的編碼行為往往還會(huì)導(dǎo)致 程序出現(xiàn)更多的隱含錯(cuò)誤。 為規(guī)范編碼行為，增強(qiáng)程序代碼的可讀性、可維護(hù)性，提高編碼質(zhì)量與效率，保障應(yīng)用軟 件產(chǎn)品整體品質(zhì)與可持續(xù)開(kāi)發(fā)性，特制定本規(guī)范。本規(guī)范分 C/C+編碼規(guī)范、Java 編碼規(guī)范、 PB 編碼規(guī)范三篇，分別從代碼組織、命名、注釋、編碼風(fēng)格、編譯等方面加以闡述。規(guī)范文本 分為規(guī)則與建議兩種，其中規(guī)則是強(qiáng)制執(zhí)行的條款，建議則由程序員根據(jù)實(shí)際情況靈活掌握。 第一篇第一篇C/C+C/C+編碼規(guī)范編碼規(guī)范 第一章第一章代碼

7、組織代碼組織 規(guī)則規(guī)則 1: 1: 使用不同的文件分別放置模塊的約束與實(shí)現(xiàn)。C+程序的約束文件使用.hpp 做擴(kuò)展 名，實(shí)現(xiàn)文件使用.cpp 做擴(kuò)展名；C 程序的約束文件使用.h 做擴(kuò)展名，實(shí)現(xiàn)文件使用.c 做擴(kuò)展 名。 規(guī)則規(guī)則 2: 2: 一個(gè)模塊可以包含一個(gè)類或功能上緊密聯(lián)系的多個(gè)類。禁止將功能關(guān)聯(lián)松散的多 個(gè)類，放置到一個(gè)模塊中。 規(guī)則規(guī)則 3: 3: 模塊約束應(yīng)僅包含模塊對(duì)外提供的功能，禁止將模塊內(nèi)部使用的功能聲明在模塊 約束中。下例中 IsChineseChar()是內(nèi)部使用的函數(shù)，不提供給外部應(yīng)用使用，因此不能在 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; 規(guī)則規(guī)則 4: 4: 簡(jiǎn)單應(yīng)用應(yīng)創(chuàng)建下列目錄結(jié)構(gòu)，模

9、塊程序代碼應(yīng)分別放置到 src/include 目錄與 src/source 目錄，編譯文件放置到 src/source 目錄，編譯后的可執(zhí)行文件放置到 rel/bin 目錄， 靜態(tài)庫(kù)或動(dòng)態(tài)庫(kù)放置到 rel/lib 目錄（應(yīng)用使用的外部庫(kù)及頭文件放置在 rel 同級(jí)的 lib 與 lib/include 目錄） 。 Work Directory src source makefile *.cpp *.c include *.hpp *.h rel bin lib 規(guī)則規(guī)則 5: 5: 復(fù)雜應(yīng)用應(yīng)分子系統(tǒng)創(chuàng)建目錄結(jié)構(gòu)，模塊程序代碼應(yīng)分別放置到 src/module/include 目錄與 src

10、/module/source 目錄，應(yīng)用編譯文件放置到 src 目錄，編譯后 的可執(zhí)行文件放置到 rel/bin 目錄，靜態(tài)庫(kù)或動(dòng)態(tài)庫(kù)放置到 rel/lib 目錄。 （應(yīng)用使用的外部庫(kù) 及頭文件放置在 rel 同級(jí)的 lib 與 lib/include 目錄） 規(guī)則規(guī)則 6: 6: 各子系統(tǒng)可以創(chuàng)建獨(dú)立的編譯文件并放置到 src/module/source 目錄，編譯后的 可執(zhí)行文件放置到 rel/bin/module 目錄或 rel/bin，靜態(tài)庫(kù)或動(dòng)態(tài)庫(kù)放置到 rel/lib/module 或 rel/lib 目錄。此時(shí)，應(yīng)創(chuàng)建一個(gè)編譯全部子系統(tǒng)的編譯文件或腳本放置到 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 第二章第二章命名命名 規(guī)則規(guī)則 7: 7: 命名應(yīng)遵循下列原則： 應(yīng)簡(jiǎn)單清晰通俗； 應(yīng)使用英文命名，禁止使用中文命名； 應(yīng)盡量選擇通用詞匯； 應(yīng)使用完整單詞或詞組，避免使用簡(jiǎn)稱； 應(yīng)準(zhǔn)確表達(dá)其含義； 避免同時(shí)使用易混淆的字母與數(shù)字，如

12、1 與 l，0 與 o； 禁止使用只靠大小寫區(qū)分的多個(gè)名稱； 多單詞組成的名稱，單詞的首字母應(yīng)大寫，如 FileName。 規(guī)則規(guī)則 8: 8: 名稱太長(zhǎng)超過(guò) 15 字符時(shí)應(yīng)使用簡(jiǎn)稱。簡(jiǎn)稱應(yīng)遵循： 應(yīng)使用標(biāo)準(zhǔn)的或常用的簡(jiǎn)寫，如 Temp（tmp） ，Length（len） ； 應(yīng)用范圍內(nèi)簡(jiǎn)寫應(yīng)一致且規(guī)范，避免各處簡(jiǎn)寫各不相同； 簡(jiǎn)寫可以使用單詞的前一個(gè)或多個(gè)字母，如 Channel（Chan） 、Connect（Conn） ；也 可以使用去掉所有的不在詞頭的元音字母，如 screen（scrn） ，primtive（prmv） ； 多個(gè)單詞組成的名稱，使用有意義的單詞或去掉無(wú)用的后綴并簡(jiǎn)稱，如

13、 Count of Failure（FailCnt） ，Paging Request（PagReq） 。 2.12.1文件命名文件命名 規(guī)則規(guī)則 9: 9: 文件命名應(yīng)使用模塊名的小寫字母形式。禁止使用漢字或大、小寫字母混用作為 代碼文件名。 2.22.2變量命名變量命名 規(guī)則規(guī)則 10: 10: 變量命名主要采用匈牙利命名法，格式為作用域范圍前綴_前綴基本類型名 稱。其中，作用域范圍前綴、前綴以小寫字母表示且可選，基本類型以小寫字母表示且必選。 常用前綴符常用前綴符 前綴符含義例子 g_ 全局變量g_stSystem, g_cMacType， g_strSysName s_ 靜態(tài)變量s_nC

14、urCnt，s_strStaticName，s_pSysTime m_ 類數(shù)據(jù)成員m_nBankType，m_sWrkBuffer, m_strMyName h 句柄類變量hnFileHandle，hnSocket，hpProcHandle p 指針類變量psReadBuff，pstrRetStr，ppTarget a 數(shù)組類變量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 等價(jià)的 32 位整數(shù) dwDOUBLE WORD 與 unsigned long 等價(jià)的 64 位整數(shù) em 枚舉型變量 emDays, emColors, emSet st 結(jié)構(gòu)型編碼stSystem，stCtrlData, stSet 規(guī)則規(guī)則 11: 11: 禁止使用單字母作為變量名。但下列常用單字母變量除外： 常用單字母變量常用單字母變量 變量類型說(shuō)明 i,j,k,m,nint 循環(huán)變量 cchar 單字符變量 schar 字符數(shù)組變量 x,yint 位置變量 pchar* 指針變量 2.32.3常量與宏命名常量與宏命名 規(guī)則規(guī)則 12:

17、 12: 常量與宏應(yīng)使用全大寫名稱，多詞組名稱使用_分隔各單詞，并使用斷行注釋說(shuō)明 其含義如： const int MAX_BUFF_SIZE = 1024 / 最大存儲(chǔ)區(qū)字節(jié)數(shù) #define MAX_FRAME_SIZE 512 / 單幀的最大長(zhǎng)度 規(guī)則規(guī)則 13: 13: 作為錯(cuò)誤碼或返回碼的宏，應(yīng)使用 E_類型_NAME 形式，并使用斷行注釋說(shuō)明其含 義。 #define E_FILE_NOTFOUND 61101001 / 文件不存在! #define E_DB_SELECT_FAIL 62301050 / 選取數(shù)據(jù)庫(kù)失敗! #define E_SYS_INVALID_STATUS

18、62301001 / 系統(tǒng)狀態(tài)非法! 規(guī)則規(guī)則 14: 14: 作為編譯條件的宏，應(yīng)使用_形式。如： #ifdef _NONE_THROW_ #endif #ifndef _FOR_CCPC_ #endif 規(guī)則規(guī)則 15: 15: 為防止重復(fù)包含而定義的頭文件預(yù)處理宏，應(yīng)使用_NAME_HPP_（C+）或 _NAME_H_（C）形式，其中 NAME 為模塊名稱。如： #ifndef _CSIGNAL_HPP_ #define _CSIGNAL_HPP_ #endif #ifndef _CSIGNAL_H_ #define _CSIGNAL_H_ #endif 2.42.4類命名類命名 規(guī)則規(guī)

19、則 16: 16: 類命名應(yīng)使用字符 C|T名稱形式。其中名稱應(yīng)使用名詞或名詞短語(yǔ)，且每個(gè)單詞 首字母大寫。如：CSignal，CFile，CString，CTagMgr。 2.52.5函數(shù)命名函數(shù)命名 規(guī)則規(guī)則 17: 17: 函數(shù)命名應(yīng)使用能夠表達(dá)函數(shù)功能的英文動(dòng)詞或動(dòng)賓結(jié)構(gòu)短語(yǔ)，且每個(gè)單詞的首 字母大寫。如：GetName()，StrTrimLeft()，KillProc()。禁止在函數(shù)名稱中使用非字母或數(shù) 字的其他字符，如下劃線_。 建議建議 1: 1: 不應(yīng)在函數(shù)名中使用數(shù)字，如：GetName1()，Kill2()。但數(shù)字是短語(yǔ)一部分的， 可以使用，如 KillSigusr2()。

20、 2.62.6參數(shù)命名參數(shù)命名 建議建議 2: 2: 函數(shù)或方法的參數(shù)命名參考變量命名，但應(yīng)使用 In，Out、Ret 等簡(jiǎn)寫修飾參數(shù)， 增加函數(shù)聲明的可讀性。如： BOOL IsSpaceStr(LPCSTR sInStr, ULONG nMaxLen = 0, ULONG* plRetOffset = NULL); void HexToBin(LPCSTR sInStr ,BYTE * psOutStr,ULONG * plRetSize = NULL); 第三章第三章注釋注釋 規(guī)則規(guī)則 18: 18: 程序代碼中增加注釋的目標(biāo)是幫助對(duì)程序的閱讀理解，不宜太多或太少，太多則 會(huì)對(duì)閱讀產(chǎn)生干

21、擾，太少則不利于代碼理解，因此只在必要的地方才加注釋，且準(zhǔn)確、易懂、 簡(jiǎn)潔。 3.13.1文檔化注釋文檔化注釋 3.1.13.1.1文件注釋文件注釋 規(guī)則規(guī)則 19: 19: 文件注釋放置在文件頭部，主要包括此文件的功能說(shuō)明，編寫人和修改人以及編 寫和修改的日期，版權(quán)聲明，版本等信息，應(yīng)盡量使用中文。注釋格式如下： /* * file filename.hppfilename.hpp * brief 文件簡(jiǎn)要說(shuō)明文件簡(jiǎn)要說(shuō)明 * * 文件詳細(xì)說(shuō)明文件詳細(xì)說(shuō)明 * * author * - 時(shí)間時(shí)間 作者作者 1 1 貢獻(xiàn)貢獻(xiàn) 1 1 * - 時(shí)間 作者 2 貢獻(xiàn) 2 * - 時(shí)間 作者 3 貢

22、獻(xiàn) 3 * * version * - 時(shí)間時(shí)間 版本版本 1 1 簡(jiǎn)要版本說(shuō)明簡(jiǎn)要版本說(shuō)明 1 1 * - 時(shí)間 版本 2 簡(jiǎn)要版本說(shuō)明 2 * * par 其他重要信息： * 其他重要信息說(shuō)明 * * warning 警告信息 * * par 版權(quán)信息： * 版本聲明信息版本聲明信息 */ 例： /* * file csignal.hpp * brief UNIX 信號(hào)函數(shù)封裝類 * * 本類封裝部分 UNIX 信號(hào)處理函數(shù)，簡(jiǎn)化在 UNIX 下編寫信號(hào)處理程序的編碼難度。 * 本類主要提供下列三類方法： * - 信號(hào)集合管理，提供信號(hào)集合的添加、刪除、判斷功能； * - 信號(hào)句柄管理，提

23、供設(shè)置與獲取信號(hào)處理函數(shù)功能； * - 信號(hào)處理，設(shè)置與獲取阻塞信號(hào)集、發(fā)送信號(hào)、等待信號(hào)功能。 * * author * - 2007-03-05 lny 創(chuàng)建初始版本 * - 2007-03-07 lny 添加文檔注釋信息 * version * - 2007-03-05 V1.0 創(chuàng)建初始版本 * - 2007-03-07 V2.0 添加文檔注釋信息 * * warning 本類不能在 WIN32 操作系統(tǒng)使用。 * * par 版權(quán)信息： * Copyright(C)Copyright(C) 2007-20072007-2007 CNCC/CDCCNCC/CDC */ 注：粗體字為需定

24、制化的內(nèi)容；蘭色字為可選的內(nèi)容，如果沒(méi)有這些內(nèi)容，請(qǐng)刪除。下同。 3.1.23.1.2類注釋類注釋 規(guī)則規(guī)則 20: 20: 類注釋放置在類聲明前，主要介紹類的功能及相關(guān)說(shuō)明。注釋格式如下： /* * brief 類簡(jiǎn)要說(shuō)明類簡(jiǎn)要說(shuō)明 * * 類詳細(xì)說(shuō)明類詳細(xì)說(shuō)明 * * par 其他重要信息 * 其他重要信息說(shuō)明 * * par 變更歷史： * - 時(shí)間 作者 修改說(shuō)明 */ 例： /* * brief UNIX 信號(hào)處理函數(shù)封裝類 * * 本類封裝部分 UNIX 信號(hào)處理函數(shù)，簡(jiǎn)化在 UNIX 下編寫信號(hào)處理程序的編碼難度。 * 本類主要提供下列三類方法： * - 信號(hào)集合管理，提供信號(hào)集

25、合的添加、刪除、判斷功能； * - 信號(hào)句柄管理，提供設(shè)置與獲取信號(hào)處理函數(shù)功能； * - 信號(hào)處理，設(shè)置與獲取阻塞信號(hào)集、發(fā)送信號(hào)、等待信號(hào)功能。 * * warning 本類不能在 WIN32 操作系統(tǒng)使用。 */ class CSignal 3.1.33.1.3函數(shù)或方法注釋函數(shù)或方法注釋 規(guī)則規(guī)則 21: 21: 函數(shù)或方法注釋放置在其聲明前，主要介紹函數(shù)的功能、參數(shù)、返回值、異常、 使用說(shuō)明、范例、引用關(guān)系、變更信息等信息。注釋格式如下： /* * brief 函數(shù)功能簡(jiǎn)要說(shuō)明函數(shù)功能簡(jiǎn)要說(shuō)明 * param in|out 參數(shù)名稱 1 參數(shù) 1 簡(jiǎn)要說(shuō)明； * param in|o

26、ut 參數(shù)名稱 2 參數(shù) 2 簡(jiǎn)要說(shuō)明。 * return 返回值說(shuō)明 * - 返回值 1 返回值 1 說(shuō)明； * - 返回值 2 返回值 2 說(shuō)明。 * exception 異常說(shuō)明 * - 異常 1 異常 1 說(shuō)明； * - 異常 2 異常 2 說(shuō)明。 * * note 函數(shù)功能詳細(xì)說(shuō)明。 * - 詳細(xì)說(shuō)明 1； * - 詳細(xì)說(shuō)明 2。 * warning 警告信息 * deprecated 函數(shù)即將失效警告 * see 引用說(shuō)明 * * par 使用范例: * code * 例子程序 * endcode * * par 算法或流程說(shuō)明: * 詳細(xì)算法或流程說(shuō)明 * * par 變更歷史：

27、 * - 時(shí)間 作者 修改說(shuō)明 */ 例： /* * brief 添加一個(gè)或多個(gè)信號(hào)到信號(hào)集合。 * param out stSet 要操作的信號(hào)集合； * param in nSignal 要添加到集合的信號(hào)； * param in nOtherSignal 要添加到集合的其他信號(hào)。 * return 添加失敗返回負(fù)整數(shù)，失敗原因可以從 errno 獲取。 * note 如果要添加多個(gè)信號(hào)，則必須使用 0 作為最后一個(gè)信號(hào)。 * warning 如果添加多個(gè)信號(hào)時(shí)沒(méi)有使用 0 作結(jié)束，則程序可能異常中止！ * 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: 重要的或復(fù)雜的函數(shù)，應(yīng)提供算法說(shuō)明或使用范例。如： 例： /* * brief 根據(jù)行號(hào)與密碼生成報(bào)尾校驗(yàn)碼作為身份認(rèn)證串。 * param in

29、 sBankCode 行號(hào)； * param in sPassword 密碼。 * return 身份認(rèn)證串。 * par 算法介紹： * -# 計(jì)算 sBankCode + sPassword 的 MD5 數(shù)字摘要，輸出 32 位字符； * -# 取 32 位字符的 0，5，10，15，16，21，26，31 位作 16 位字符串的偶數(shù)位； * -# 取AUTHBEPS各位作 16 位字符串的奇數(shù)位； * -# 加密這 16 位的字符串，得到 32 位的字符串作為認(rèn)證串。 */ CString BuildAuthStr(LPCSTR sBankCode, LPCSTR sPassword);

30、 3.1.43.1.4數(shù)據(jù)成員注釋數(shù)據(jù)成員注釋 規(guī)則規(guī)則 22: 22: 類的每個(gè)數(shù)據(jù)成員均使用斷行注釋。注釋格式如下： 例： class CMTMsg private: BOOL m_bBodyInFile;/ 是文件型報(bào)文？ CString m_strFileName;/ 文件型報(bào)文的文件名 CString m_strBody;/ 直接設(shè)置的報(bào)體串 CMTMsgHeader m_Header;/ 報(bào)頭對(duì)象 CMTMsgTail m_Tail;/ 報(bào)尾對(duì)象 CMTBatHeader m_BatHeader;/ 批量業(yè)務(wù)頭對(duì)象 3.1.53.1.5結(jié)構(gòu)注釋結(jié)構(gòu)注釋 規(guī)則規(guī)則 23: 23: 結(jié)

31、構(gòu)可使用簡(jiǎn)單注釋，也可使用與類相同的注釋格式，其數(shù)據(jù)成員使用斷行注釋。 注釋格式如下： 例： /* 報(bào)頭結(jié)構(gòu)，總長(zhǎng)度 138 字節(jié)。*/ struct CMTHeaderMap char blockMark3;/ 報(bào)頭塊前綴 = 1:。 char verID1;/ 版本號(hào)，保留 = 0。 char mesgLen6;/ 報(bào)文總長(zhǎng)度，保留，目前為空白。 char appTradeCode8;/ 業(yè)務(wù)碼 0 位(系統(tǒng)號(hào)) 1-3 位 CMT 號(hào) 4 位 節(jié)點(diǎn) 5-7 位 保留。 char startAddr12;/ 報(bào)文源地址，即報(bào)文發(fā)起人。 char destAddr12;/ 報(bào)文目標(biāo)地址，即報(bào)

32、文接收人。 char mesgPurp1;/ 報(bào)文用途，保留。 char outForm1;/ 輸出標(biāo)識(shí)，保留。 char mesgIDMSGID_LEN;/ 報(bào)文標(biāo)識(shí)號(hào)，報(bào)文發(fā)起人生成，通信層唯一確定 一個(gè)報(bào)文。 char mesgReqNoREQUESTID_LEN; / 報(bào)文參考號(hào)，報(bào)文發(fā)起人生成，回應(yīng)報(bào)文帶 回進(jìn)行報(bào)文匹配。 char workDate8;/ 報(bào)文日期，格式為 YYYYMMDD。 char sentTime14;/ 報(bào)文時(shí)間，格式為 YYYYMMDDHHMISS。 char expTime4;/ 報(bào)文有效期，保留，0-0 xFFFF=65535。 char deliTi

33、me6;/ 報(bào)文提交時(shí)間，保留，格式為 HHMISS。 char mesgPRI1;/ 報(bào)文優(yōu)先級(jí)，0 x0-0 xF=15。 char reserve20;/ 保留域。 char finalMark1;/ 報(bào)頭塊后綴 = 。 ; 3.1.63.1.6宏與變量注釋宏與變量注釋 規(guī)則規(guī)則 24: 24: 宏與變量使用簡(jiǎn)單注釋或斷行注釋。特別重要的宏可以使用與類相同的文檔注釋。 注釋格式如下： 例： #define MBT_PREFIX / 報(bào)文塊開(kāi)始標(biāo)志 #define MBT_SUFFIX / 報(bào)文塊結(jié)束標(biāo)志 #define MBT_HEADER 1: / 報(bào)頭塊開(kāi)始標(biāo)志 #define MB

34、T_BUSINESSHEADER 2: / 業(yè)務(wù)頭塊開(kāi)始標(biāo)志 #define MBT_BUSINESSDATA 3: / 正文塊開(kāi)始標(biāo)志 #define MBT_TAIL C: / 報(bào)尾塊開(kāi)始標(biāo)志 #define MBT_FILE F: / 文件說(shuō)明塊開(kāi)始標(biāo)志 #define MBT_BATHEADER B: / 批量信息塊開(kāi)始標(biāo)志 #define TAG_PREFIX : / TAG 名開(kāi)始標(biāo)志 #define TAG_SUFFIX : / TAG 名結(jié)束標(biāo)志 #define MSGID_LEN 20 / 報(bào)文標(biāo)識(shí)號(hào)長(zhǎng)度(MSGID) #define REQUESTID_LEN 20 / 報(bào)

35、文參考號(hào)長(zhǎng)度(REQID) 例： /* 業(yè)務(wù)頭保留域長(zhǎng)度 */ #define CMTBH_RESERVED_LEN 16 例： /* * brief 短報(bào)文正文體最大長(zhǎng)度。 * * 此長(zhǎng)度應(yīng)根據(jù) MQCMT 類定義最大消息長(zhǎng)度進(jìn)行調(diào)整，超過(guò)此長(zhǎng)度的報(bào)文應(yīng)分為多個(gè)報(bào) 文片斷傳輸。 * * par 計(jì)算公式： * code * 最大長(zhǎng)度 = MQCMT 消息長(zhǎng)度 - sizeof(CMTMsgHeader) - sizeof(CMTMsgTail) - sizeof(MQMsg) +1 * = MQCMT 最大消息長(zhǎng)度 - 175 * endcode * 目前，MQCMT 類定義的最大消息長(zhǎng)度為

36、 1M=1048576 字節(jié)。 */ #define SHORT_MSGBODY_MAX_LEN 1000000 3.1.73.1.7文檔注釋技巧文檔注釋技巧 建議建議 4: 4: 為使 doxygen 工具能生成更好的文檔，編寫文檔注釋時(shí)參考下列技巧： 注釋中使用的標(biāo)識(shí)符前后均應(yīng)留一個(gè)空格，以便 doxygen 識(shí)別此標(biāo)識(shí)符，并自動(dòng)生成 一個(gè)引用連接。如： /* * * par CMT 報(bào)文格式說(shuō)明： * - CMT 報(bào)文由報(bào)頭( CMTMsgHeader )、可選的批量業(yè)務(wù)頭( CMTBatHeader )、正文 體、報(bào)尾( CMTMsgTail )組成。其中除正文體外，其余各塊都是定長(zhǎng)的

37、； * - 正文體由一個(gè)或多個(gè)業(yè)務(wù)塊組成。每個(gè)業(yè)務(wù)塊由一個(gè)定長(zhǎng)的業(yè)務(wù)頭( CMTBusinessHeader )與一個(gè)變長(zhǎng)正文塊( CMTBusinessData )組成； * - 正文塊( CMTBusinessData )由一個(gè)或多個(gè) TAG 碼:TAG 值對(duì)(報(bào)文域)組成，部分 TAG 值又可由多個(gè)定長(zhǎng)子域組成； * - 正文體可放置在報(bào)文中，也可存儲(chǔ)在文件中，而在報(bào)文中僅放置文件名； * - 當(dāng)正文體在文件中，則說(shuō)明批量業(yè)務(wù)頭、業(yè)務(wù)頭、正文塊存儲(chǔ)在文件中。 */ 注釋中可使用 HTML 標(biāo)記美化最終文檔，但別濫用美化標(biāo)記； 較長(zhǎng)的文檔注釋需要分段說(shuō)明時(shí)，使用分段。如果需要段首縮進(jìn)兩字符

38、，使用全 角的空格。 文檔注釋中可以使用par 增加一個(gè)小節(jié)，靈活使用此標(biāo)記可以任意地?cái)U(kuò)展文檔的結(jié)構(gòu)， 滿足特殊描述的需要。如： /* * * * par 算法原理： * 計(jì)算機(jī)內(nèi)部運(yùn)算使用的基數(shù)是 2，即滿 2 進(jìn)位。如果計(jì)算機(jī)字長(zhǎng)為 32 位，則最大 可以表示的整數(shù)為 4294967296. * 為了突破計(jì)算機(jī)最大整數(shù)的限制，可以采取兩種做法，一是擴(kuò)大基數(shù)，二是增加字 長(zhǎng)。 * 根據(jù)此原理，本類使用 65536 作為基數(shù)，每個(gè)整數(shù)的最大位數(shù) 10(unsigned int array 10)， * 因此可以最大整數(shù)是 65536 的 10 次方，約 1.4e48。通過(guò)變更基數(shù)或位數(shù)，本類理

39、 論上可以處理的任意整數(shù)。 */ 需要生成圓點(diǎn)列表時(shí)使用，需要生成編號(hào)列表時(shí)使用#。 需要特別說(shuō)明一段文字，可以使用 code/endcode。如： * par 計(jì)算公式： * code * 最大長(zhǎng)度 = MQCMT 消息長(zhǎng)度 - sizeof(CMTMsgHeader) - sizeof(CMTMsgTail) - sizeof(MQMsg) +1 * = MQCMT 最大消息長(zhǎng)度 - 175 * endcode 為使 doxygen 正確生成函數(shù)或方法的連接，注釋中的函數(shù)名或方法名前后應(yīng)留一個(gè)空 格。如該函數(shù)或方法沒(méi)有重載，則不必使用參數(shù)列表，如 GetTag()。如該函數(shù)或方法 重載，則

40、應(yīng)必須使用參數(shù)（類型）列表，如 GetTag(LPCSTR, AMOUNT return; / 清除行計(jì)數(shù) static int nLineChars = 0; / 輸出的行長(zhǎng)度計(jì)數(shù) if(bResetLineChars) / 行計(jì)數(shù)復(fù)位 nLineChars = 0; / 計(jì)算輸出長(zhǎng)度 int nOutLen = 2*4*(nInpLen/3 +1); / 考慮到要添加回車換行，多分配點(diǎn)空間 char * p = strOutStr.GetBufferSetLength(nOutLen); memset(p, 0, nOutLen); 例：邏輯性較強(qiáng) / 1.BankCode + Passw

41、ord CString strWrkStr = sWrkBankCode + sWrkPassword; / 2.計(jì)算 MD5 指紋 CString strMD5 = md5.HashBuffer(BYTE*)strWrkStr.GetBuffer(0), strWrkStr.GetLength(); / 3.選取八位數(shù)字指紋 char* p = strMD5.GetBuffer(0); char sTmpStr17; int ii=0; memset(sTmpStr, 0, sizeof(sTmpStr); for(ii=0; ii8; +ii) sTmpStr2*ii = p4*ii +

42、ii%4; / 4.組合固定串 p = AUTHBEPS; for(ii=0; ii80 字符）或表達(dá)式應(yīng)分成多行書(shū)寫。語(yǔ)句應(yīng)在逗號(hào)分隔符處劃分新 行；表達(dá)式應(yīng)在低優(yōu)先級(jí)操作符處劃分新行，操作符放在新行之首。劃分出的新行要進(jìn)行適當(dāng) 的縮進(jìn)，使排版整齊，語(yǔ)句易讀。 例： if(!IsNumberString(stCIS410Detail.sBankCode) | strlen(stCIS410Detail.sBankCode) != 12 | strcmp(stCIS410Detail.sBankCode, stCIS410Detail.sOrgBankCode) = 0) 應(yīng)書(shū)寫為： If (

43、!IsNumberString(stCIS410Detail.sBankCode) | strlen(stCIS410Detail.sBankCode) != 12 | strcmp(stCIS410Detail.sBankCode, stCIS410Detail.sOrgBankCode) = 0) THROW_OUT(E_INVALIDLIST, StrPrint(票交機(jī)構(gòu)行別非數(shù)字或長(zhǎng)度非 3 位! %s, stCIS410Detail.sClsCode).GetBuffer(0); 應(yīng)書(shū)寫為： THROW_OUT(E_INVALIDLIST, StrPrint(票交機(jī)構(gòu)行別非數(shù)字或長(zhǎng)度

44、非 3 位! %s, stCIS410Detail.sClsCode).GetBuffer(0); 建議建議 8: 8: 對(duì)結(jié)構(gòu)的多個(gè)數(shù)據(jù)成員賦值時(shí)，將等號(hào)對(duì)齊。 例： rect.top = 0; rect.left = 0; rect.right = 300; rect.bottom = 200; 應(yīng)書(shū)寫為： rect.top = 0; rect.left = 0; rect.right = 300; rect.bottom = 200; 建議建議 9: 9: 定義多個(gè)宏或初始化多個(gè)變量時(shí)，將值對(duì)齊。 例： #define MBT_PREFIX / 報(bào)文塊開(kāi)始標(biāo)志 #define MBT_S

45、UFFIX / 報(bào)文塊結(jié)束標(biāo)志 #define MBT_HEADER 1: / 報(bào)頭塊開(kāi)始標(biāo)志 #define MBT_BUSINESSHEADER 2: / 業(yè)務(wù)頭塊開(kāi)始標(biāo)志 #define MBT_BUSINESSDATA 3: / 正文塊開(kāi)始標(biāo)志 #define MBT_TAIL C: / 報(bào)尾塊開(kāi)始標(biāo)志 #define MBT_FILE F: / 文件說(shuō)明塊開(kāi)始標(biāo)志 #define MBT_BATHEADER B: / 批量信息塊開(kāi)始標(biāo)志 #define TAG_PREFIX : / TAG 名開(kāi)始標(biāo)志 #define TAG_SUFFIX : / TAG 名結(jié)束標(biāo)志 應(yīng)書(shū)寫為： #d

46、efine MBT_PREFIX / 報(bào)文塊開(kāi)始標(biāo)志 #define MBT_SUFFIX / 報(bào)文塊結(jié)束標(biāo)志 #define MBT_HEADER 1: / 報(bào)頭塊開(kāi)始標(biāo)志 #define MBT_BUSINESSHEADER 2: / 業(yè)務(wù)頭塊開(kāi)始標(biāo)志 #define MBT_BUSINESSDATA 3: / 正文塊開(kāi)始標(biāo)志 #define MBT_TAIL C: / 報(bào)尾塊開(kāi)始標(biāo)志 #define MBT_FILE F: / 文件說(shuō)明塊開(kāi)始標(biāo)志 #define MBT_BATHEADER B: / 批量信息塊開(kāi)始標(biāo)志 #define TAG_PREFIX : / TAG 名開(kāi)始標(biāo)志 #

47、define TAG_SUFFIX : /m_chMsgType = MQ_MT_TAIL; iSegmentFlag = SF_LASTSEGMENT; strncpy(ptr-m_pBody, (char*) pTail, sizeof(CMTTailMap); return Put(LPCSTR)ptr, strMsgId, sizeof(MQMsg) + sizeof(CMTTailMap) -1, iSegmentFlag, nPriority, iFeedbackCode); 應(yīng)書(shū)寫為： ptr-m_chMsgType = MQ_MT_TAIL; iSegmentFlag = SF

48、_LASTSEGMENT; strncpy(ptr-m_pBody, (char*) pTail, sizeof(CMTTailMap); return Put(LPCSTR)ptr, strMsgId, sizeof(MQMsg) + sizeof(CMTTailMap) -1, iSegmentFlag, nPriority, iFeedbackCode); 規(guī)則規(guī)則 33: 33: 比較操作符，賦值操作符，算術(shù)操作符，邏輯操作符，位域操作符等雙目運(yùn)算符 前后應(yīng)加空格與操作數(shù)隔開(kāi)。 例： i=i+1; if(i10) i=(i2); 應(yīng)書(shū)寫為： i = i + 1; if (i 10) i

49、 = (ii 2); 規(guī)則規(guī)則 34: 34: 逗號(hào)、分號(hào)后面應(yīng)加空格，但前面不應(yīng)加空格。 例： for(int ii=0 ; ii10;ii+) 應(yīng)書(shū)寫為： for (int ii = 0; ii 10) for(ii = 0; ii 10) for (ii = 0; ii - m_nNamem_nName = = str;str; 應(yīng)書(shū)寫為： CString str = stSet.GetName(strOrgName);stSet.GetName(strOrgName); if (str(str = uname)uname) pOldSet-m_nNamepOldSet-m_nName

50、= = str;str; 4.1.34.1.3括號(hào)使用括號(hào)使用 規(guī)則規(guī)則 37: 37: 復(fù)雜的表達(dá)式應(yīng)使用括號(hào)以避免二義性，不應(yīng)依賴運(yùn)算符優(yōu)先級(jí)。如：if (i 0) | (i = -12)、(p+) + 1。 規(guī)則規(guī)則 38: 38: 位運(yùn)算時(shí)應(yīng)使用括號(hào)，如：i = (nSumVal 4)。 規(guī)則規(guī)則 39: 39: return 與 throw 非函數(shù)，不應(yīng)使用括號(hào)。如：return nRetCode。 4.24.2頭文件頭文件 規(guī)則規(guī)則 40: 40: 頭文件應(yīng)使用防止重復(fù)包含宏括整個(gè)頭文件部分。宏名應(yīng)為_(kāi)模塊名_HPP_或_ 模塊名_H_。注意：注意：#endif#endif 后必須

51、保留一個(gè)空行，否則部分編譯器會(huì)報(bào)警告信息。后必須保留一個(gè)空行，否則部分編譯器會(huì)報(bào)警告信息。 規(guī)則規(guī)則 41: 41: 本模塊需要的頭文件以及外部函數(shù)，應(yīng)全部列在本模塊頭文件的首部且緊臨防重 復(fù)包含宏，并按先系統(tǒng)級(jí)、公共級(jí)、應(yīng)用級(jí)、本模塊級(jí)的順序擺放。盡量不在實(shí)現(xiàn)文件中包含 除本模塊頭文件外的其他頭文件以及外部函數(shù)。 規(guī)則規(guī)則 42: 42: 頭文件引用禁止含路徑信息，無(wú)論是全路徑還是相對(duì)路徑。 規(guī)則規(guī)則 43: 43: 禁止在頭文件中定義變量或常量。 例：頭文件 cis401.hpp #ifndef _MODULE_NAME_HPP_ #define _MODULE_NAME_HPP_ #in

52、clude #include#include /PUBLIB/src/include/common.hpp/PUBLIB/src/include/common.hpp #include#include ./include/cispub.hpp./include/cispub.hpp intint g_nUserCodeg_nUserCode = = 0;0; #endif 例：實(shí)現(xiàn)文件 cis401.cpp #include#include #include#include cstring.hppcstring.hpp #include#include ./include/cis401.hpp

53、./include/cis401.hpp externextern longlong GetFileSize(LPCSTRGetFileSize(LPCSTR sFileName);sFileName); cis401.hpp 應(yīng)書(shū)寫為： #ifndef _MODULE_NAME_HPP_ #define _MODULE_NAME_HPP_ #include #include #include common.hpp #include cstring.hpp #include cispub.hpp extern long GetFileSize(LPCSTR sFileName); extern

54、 int g_nUserCode; #endif cis401.cpp 應(yīng)書(shū)寫為： #include cis401.hpp int g_nUserCode = 0; 4.34.3宏定義宏定義 建議建議 15: 15: 靈活使用編譯宏解決平臺(tái)或版本的兼容性問(wèn)題。 例：.cpp #ifdef WIN32 / in WIN32 void printTrace(LPCSTR lpName, LPCSTR lpText, .) char szTmp4096; memset(szTmp, 0, sizeof(szTmp); va_list argList; va_start(argList, lpText

55、); _vsprintf(szTmp,_vsprintf(szTmp, lpText,lpText, argList);argList); va_end(argList); fprintf(stderr, %s %s: %sn, StrCurrentTime(YYYY-MM-DD HH:MM:SS).GetBuffer(0), lpName, szTmp); #else / in UNIX void printTrace(LPCSTR lpName, LPCSTR lpText, .) char szTmp4096; memset(szTmp, 0, sizeof(szTmp); va_lis

56、t argList; va_start(argList, lpText); vsprintf(szTmp,vsprintf(szTmp, lpText,lpText, argList);argList); va_end(argList); fprintf(stderr, %s %s: %sn, StrCurrentTime(YYYY-MM-DD HH:MM:SS).GetBuffer(0), lpName, szTmp); #endif 應(yīng)修改為： .hpp #ifdef WIN32 #define#define vsprintfvsprintf _vsprintf_vsprintf #end

57、if .cpp void printTrace(LPCSTR lpName, LPCSTR lpText, .) char szTmp4096; memset(szTmp, 0, sizeof(szTmp); va_list argList; va_start(argList, lpText); vsprintf(szTmp,vsprintf(szTmp, lpText,lpText, argList);argList); va_end(argList); fprintf(stderr, %s %s: %sn, StrCurrentTime(YYYY-MM-DD HH:MM:SS).GetBu

58、ffer(0), lpName, szTmp); 規(guī)則規(guī)則 44: 44: 宏表達(dá)式的變量應(yīng)使用括號(hào)括，使用宏時(shí)應(yīng)避免傳遞表達(dá)式給宏變量。 例： #define MAX(a,b) (ab)?a:b 應(yīng)書(shū)寫為： #define MAX(a,b) (a)(b)?(a):(b) 調(diào)用： int nMax = MAX(i+, b+); 應(yīng)書(shū)寫為： int nTmpi = i+; int nTmpb = b+; int nMax = MAX(nTmpi, nTmpb); 規(guī)則規(guī)則 45: 45: 單條語(yǔ)句構(gòu)成的宏不應(yīng)使用分號(hào)作為宏結(jié)束；多條語(yǔ)句構(gòu)成宏時(shí)，應(yīng)使用花括號(hào) 括宏體。 例： #define Th

59、rowExceptionExt(sFileName,nErrCode,sExtMsg) ThrowFileExceptionExt(_FILE_, _LINE_, sFileName, nErrCode, sExtMsg); return nErrCode #define RETCODE(n) return n; 應(yīng)書(shū)寫成： #define ThrowExceptionExt(sFileName,nErrCode,sExtMsg) ThrowFileExceptionExt(_FILE_, _LINE_, sFileName, nErrCode, sExtMsg); return nErrCode; #define RETCODE(n) return n 規(guī)則規(guī)則 46: 46: 構(gòu)成宏體的語(yǔ)句必須完成，禁止包含語(yǔ)句塊的部分。 例： #define CLEAR_ALL(n) for(int ii = 0; ii n; ii+) CLEAR_ALL(strlen(str) strii = 0; #define CLEAR_ALL(n) for(int ii = 0; ii (n); ii+) strii = 0; 以上兩例應(yīng)書(shū)寫為： #define CLEAR_ALL(str, n) for(intint iiii = = 0