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

軟軟軟軟軟軟件件件件件件編編編編編編碼碼碼碼碼碼規(guī)規(guī)規(guī)規(guī)規(guī)規(guī)范范范范范范 文件編號(hào) RDC DED SCS SPC 00 當(dāng)前版本 作 者 審 核 人 文件狀態(tài) 草稿 正式發(fā)布 正在修改 完成日期 中國(guó)人民銀行清算總中心 支付系統(tǒng)開發(fā)中心 文檔修訂記錄 版本編號(hào)變化狀態(tài)簡(jiǎn)要說明日期變更人批準(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ù)命名 10 2 6參數(shù)命名 11 第三章第三章注釋注釋 1212 3 1文檔化注釋 12 3 2語句塊注釋 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 第一章第一章代碼組織代碼組織 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語句塊注釋 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 第五章第五章編譯編譯 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文檔化注釋 85 3 2語句塊注釋 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)目更是由很多程序員組成 的大型開發(fā)團(tuán)隊(duì)協(xié)同完成的 每個(gè)程序員都有自己的編碼經(jīng)驗(yàn)與風(fēng)格 如果缺乏統(tǒng)一的編程規(guī) 范 則可能導(dǎo)致軟件產(chǎn)品最終程序代碼風(fēng)格迥異 可讀性與可維護(hù)性均較差 不僅給程序代碼 的理解帶來障礙 也增加維護(hù)階段的工作量 此外 經(jīng)驗(yàn)證明不規(guī)范的編碼行為往往還會(huì)導(dǎo)致 程序出現(xiàn)更多的隱含錯(cuò)誤 為規(guī)范編碼行為 增強(qiáng)程序代碼的可讀性 可維護(hù)性 提高編碼質(zhì)量與效率 保障應(yīng)用軟 件產(chǎn)品整體品質(zhì)與可持續(xù)開發(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ī)范 第一章第一章代碼組織代碼組織 規(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 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) 模塊程序代碼應(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 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 目錄 Work 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ù)字 如 1 與 l 0 與 o 禁止使用只靠大小寫區(qū)分的多個(gè)名稱 多單詞組成的名稱 單詞的首字母應(yīng)大寫 如 FileName 規(guī)則規(guī)則 8 8 名稱太長(zhǎng)超過 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è)單詞組成的名稱 使用有意義的單詞或去掉無用的后綴并簡(jiǎn)稱 如 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 nCurCnt 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 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 ulRetCount 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 禁止使用單字母作為變量名 但下列常用單字母變量除外 常用單字母變量常用單字母變量 變量類型說明 i j k m nint 循環(huán)變量 cchar 單字符變量 schar 字符數(shù)組變量 x yint 位置變量 pchar 指針變量 2 32 3常量與宏命名常量與宏命名 規(guī)則規(guī)則 12 12 常量與宏應(yīng)使用全大寫名稱 多詞組名稱使用 分隔各單詞 并使用斷行注釋說明 其含義如 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 形式 并使用斷行注釋說明其含 義 define E FILE NOTFOUND 61101001 文件不存在 define E DB SELECT FAIL 62301050 選取數(shù)據(jù)庫(kù)失敗 define E SYS INVALID STATUS 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ī)則 16 16 類命名應(yīng)使用字符 C T 名稱形式 其中名稱應(yīng)使用名詞或名詞短語 且每個(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)短語 且每個(gè)單詞的首 字母大寫 如 GetName StrTrimLeft KillProc 禁止在函數(shù)名稱中使用非字母或數(shù) 字的其他字符 如下劃線 建議建議 1 1 不應(yīng)在函數(shù)名中使用數(shù)字 如 GetName1 Kill2 但數(shù)字是短語一部分的 可以使用 如 KillSigusr2 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)生干擾 太少則不利于代碼理解 因此只在必要的地方才加注釋 且準(zhǔn)確 易懂 簡(jiǎn)潔 3 13 1文檔化注釋文檔化注釋 3 1 13 1 1文件注釋文件注釋 規(guī)則規(guī)則 19 19 文件注釋放置在文件頭部 主要包括此文件的功能說明 編寫人和修改人以及編 寫和修改的日期 版權(quán)聲明 版本等信息 應(yīng)盡量使用中文 注釋格式如下 file filename hppfilename hpp brief 文件簡(jiǎn)要說明文件簡(jiǎn)要說明 文件詳細(xì)說明文件詳細(xì)說明 author 時(shí)間時(shí)間 作者作者 1 1 貢獻(xiàn)貢獻(xiàn) 1 1 時(shí)間 作者 2 貢獻(xiàn) 2 時(shí)間 作者 3 貢獻(xiàn) 3 version 時(shí)間時(shí)間 版本版本 1 1 簡(jiǎn)要版本說明簡(jiǎn)要版本說明 1 1 時(shí)間 版本 2 簡(jiǎn)要版本說明 2 par 其他重要信息 其他重要信息說明 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)句柄管理 提供設(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 注 粗體字為需定制化的內(nèi)容 蘭色字為可選的內(nèi)容 如果沒有這些內(nèi)容 請(qǐng)刪除 下同 3 1 23 1 2類注釋類注釋 規(guī)則規(guī)則 20 20 類注釋放置在類聲明前 主要介紹類的功能及相關(guān)說明 注釋格式如下 brief 類簡(jiǎn)要說明類簡(jiǎn)要說明 類詳細(xì)說明類詳細(xì)說明 par 其他重要信息 其他重要信息說明 par 變更歷史 時(shí)間 作者 修改說明 例 brief UNIX 信號(hào)處理函數(shù)封裝類 本類封裝部分 UNIX 信號(hào)處理函數(shù) 簡(jiǎn)化在 UNIX 下編寫信號(hào)處理程序的編碼難度 本類主要提供下列三類方法 信號(hào)集合管理 提供信號(hào)集合的添加 刪除 判斷功能 信號(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ù) 返回值 異常 使用說明 范例 引用關(guān)系 變更信息等信息 注釋格式如下 brief 函數(shù)功能簡(jiǎn)要說明函數(shù)功能簡(jiǎn)要說明 param in out 參數(shù)名稱 1 參數(shù) 1 簡(jiǎn)要說明 param in out 參數(shù)名稱 2 參數(shù) 2 簡(jiǎn)要說明 return 返回值說明 返回值 1 返回值 1 說明 返回值 2 返回值 2 說明 exception 異常說明 異常 1 異常 1 說明 異常 2 異常 2 說明 note 函數(shù)功能詳細(xì)說明 詳細(xì)說明 1 詳細(xì)說明 2 warning 警告信息 deprecated 函數(shù)即將失效警告 see 引用說明 par 使用范例 code 例子程序 endcode par 算法或流程說明 詳細(xì)算法或流程說明 par 變更歷史 時(shí)間 作者 修改說明 例 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í)沒有使用 0 作結(jié)束 則程序可能異常中止 see DelFromSet AddAllToSet ClearSet 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)提供算法說明或使用范例 如 例 brief 根據(jù)行號(hào)與密碼生成報(bào)尾校驗(yàn)碼作為身份認(rèn)證串 param in 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 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é)構(gòu)可使用簡(jiǎn)單注釋 也可使用與類相同的注釋格式 其數(shù)據(jù)成員使用斷行注釋 注釋格式如下 例 報(bào)頭結(jié)構(gòu) 總長(zhǎng)度 138 字節(jié) struct CMTHeaderMap char blockMark 3 報(bào)頭塊前綴 1 char verID 1 版本號(hào) 保留 0 char mesgLen 6 報(bào)文總長(zhǎng)度 保留 目前為空白 char appTradeCode 8 業(yè)務(wù)碼 0 位 系統(tǒng)號(hào) 1 3 位 CMT 號(hào) 4 位 節(jié)點(diǎn) 5 7 位 保留 char startAddr 12 報(bào)文源地址 即報(bào)文發(fā)起人 char destAddr 12 報(bào)文目標(biāo)地址 即報(bào)文接收人 char mesgPurp 1 報(bào)文用途 保留 char outForm 1 輸出標(biāo)識(shí) 保留 char mesgID MSGID LEN 報(bào)文標(biāo)識(shí)號(hào) 報(bào)文發(fā)起人生成 通信層唯一確定 一個(gè)報(bào)文 char mesgReqNo REQUESTID LEN 報(bào)文參考號(hào) 報(bào)文發(fā)起人生成 回應(yīng)報(bào)文帶 回進(jìn)行報(bào)文匹配 char workDate 8 報(bào)文日期 格式為 YYYYMMDD char sentTime 14 報(bào)文時(shí)間 格式為 YYYYMMDDHHMISS char expTime 4 報(bào)文有效期 保留 0 0 xFFFF 65535 char deliTime 6 報(bào)文提交時(shí)間 保留 格式為 HHMISS char mesgPRI 1 報(bào)文優(yōu)先級(jí) 0 x0 0 xF 15 char reserve 20 保留域 char finalMark 1 報(bào)頭塊后綴 3 1 63 1 6宏與變量注釋宏與變量注釋 規(guī)則規(guī)則 24 24 宏與變量使用簡(jiǎn)單注釋或斷行注釋 特別重要的宏可以使用與類相同的文檔注釋 注釋格式如下 例 define MBT PREFIX 報(bào)文塊開始標(biāo)志 define MBT SUFFIX 報(bào)文塊結(jié)束標(biāo)志 define MBT HEADER 1 報(bào)頭塊開始標(biāo)志 define MBT BUSINESSHEADER 2 業(yè)務(wù)頭塊開始標(biāo)志 define MBT BUSINESSDATA 3 正文塊開始標(biāo)志 define MBT TAIL C 報(bào)尾塊開始標(biāo)志 define MBT FILE F 文件說明塊開始標(biāo)志 define MBT BATHEADER B 批量信息塊開始標(biāo)志 define TAG PREFIX TAG 名開始標(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)文參考號(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)整 超過此長(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)度為 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)文格式說明 CMT 報(bào)文由報(bào)頭 CMTMsgHeader 可選的批量業(yè)務(wù)頭 CMTBatHeader 正文 體 報(bào)尾 CMTMsgTail 組成 其中除正文體外 其余各塊都是定長(zhǎng)的 正文體由一個(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)正文體在文件中 則說明批量業(yè)務(wù)頭 業(yè)務(wù)頭 正文塊存儲(chǔ)在文件中 注釋中可使用 HTML 標(biāo)記美化最終文檔 但別濫用美化標(biāo)記 較長(zhǎng)的文檔注釋需要分段說明時(shí) 使用分段 如果需要段首縮進(jìn)兩字符 使用全 角的空格 文檔注釋中可以使用 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 通過變更基數(shù)或位數(shù) 本類理 論上可以處理的任意整數(shù) 需要生成圓點(diǎn)列表時(shí)使用 需要生成編號(hào)列表時(shí)使用 需要特別說明一段文字 可以使用 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ù)或方法沒有重載 則不必使用參數(shù)列表 如 GetTag 如該函數(shù)或方法 重載 則應(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 Password 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 sTmpStr 17 int ii 0 memset sTmpStr 0 sizeof sTmpStr for ii 0 ii 8 ii sTmpStr 2 ii p 4 ii ii 4 4 組合固定串 p AUTHBEPS for ii 0 ii80 字符 或表達(dá)式應(yīng)分成多行書寫 語句應(yīng)在逗號(hào)分隔符處劃分新 行 表達(dá)式應(yīng)在低優(yōu)先級(jí)操作符處劃分新行 操作符放在新行之首 劃分出的新行要進(jìn)行適當(dāng) 的縮進(jìn) 使排版整齊 語句易讀 例 if IsNumberString stCIS410Detail sBankCode strlen stCIS410Detail sBankCode 12 strcmp stCIS410Detail sBankCode stCIS410Detail sOrgBankCode 0 應(yīng)書寫為 If 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)書寫為 THROW OUT E INVALIDLIST StrPrint 票交機(jī)構(gòu)行別非數(shù)字或長(zhǎng)度非 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)書寫為 rect top 0 rect left 0 rect right 300 rect bottom 200 建議建議 9 9 定義多個(gè)宏或初始化多個(gè)變量時(shí) 將值對(duì)齊 例 define MBT PREFIX 報(bào)文塊開始標(biāo)志 define MBT SUFFIX 報(bào)文塊結(jié)束標(biāo)志 define MBT HEADER 1 報(bào)頭塊開始標(biāo)志 define MBT BUSINESSHEADER 2 業(yè)務(wù)頭塊開始標(biāo)志 define MBT BUSINESSDATA 3 正文塊開始標(biāo)志 define MBT TAIL C 報(bào)尾塊開始標(biāo)志 define MBT FILE F 文件說明塊開始標(biāo)志 define MBT BATHEADER B 批量信息塊開始標(biāo)志 define TAG PREFIX TAG 名開始標(biāo)志 define TAG SUFFIX TAG 名結(jié)束標(biāo)志 應(yīng)書寫為 define MBT PREFIX 報(bào)文塊開始標(biāo)志 define MBT SUFFIX 報(bào)文塊結(jié)束標(biāo)志 define MBT HEADER 1 報(bào)頭塊開始標(biāo)志 define MBT BUSINESSHEADER 2 業(yè)務(wù)頭塊開始標(biāo)志 define MBT BUSINESSDATA 3 正文塊開始標(biāo)志 define MBT TAIL C 報(bào)尾塊開始標(biāo)志 define MBT FILE F 文件說明塊開始標(biāo)志 define MBT BATHEADER B 批量信息塊開始標(biāo)志 define TAG PREFIX TAG 名開始標(biāo)志 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)書寫為 ptr 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 規(guī)則規(guī)則 33 33 比較操作符 賦值操作符 算術(shù)操作符 邏輯操作符 位域操作符等雙目運(yùn)算符 前后應(yīng)加空格與操作數(shù)隔開 例 i i 1 if i 10 i i 2 應(yīng)書寫為 i i 1 if i 10 i ii 2 規(guī)則規(guī)則 34 34 逗號(hào) 分號(hào)后面應(yīng)加空格 但前面不應(yīng)加空格 例 for int ii 0 ii 10 ii 應(yīng)書寫為 for int ii 0 ii 10 for ii 0 ii 10 for ii 0 ii m nNamem nName str str 應(yīng)書寫為 CString str stSet GetName strOrgName stSet GetName strOrgName if str str uname uname pOldSet m nNamepOldSet m nName 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)為 模塊名 HPP 或 模塊名 H 注意 注意 endif endif 后必須保留一個(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 頭文件引用禁止含路徑信息 無論是全路徑還是相對(duì)路徑 規(guī)則規(guī)則 43 43 禁止在頭文件中定義變量或常量 例 頭文件 cis401 hpp ifndef MODULE NAME HPP define MODULE NAME HPP include 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 hpp cstring hpp include include include cis401 hpp include cis401 hpp externextern longlong GetFileSize LPCSTRGetFileSize LPCSTR sFileName sFileName cis401 hpp 應(yīng)書寫為 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 int g nUserCode endif cis401 cpp 應(yīng)書寫為 include cis401 hpp int g nUserCode 0 4 34 3宏定義宏定義 建議建議 15 15 靈活使用編譯宏解決平臺(tái)或版本的兼容性問題 例 cpp ifdef WIN32 in WIN32 void printTrace LPCSTR lpName LPCSTR lpText char szTmp 4096 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 s n StrCurrentTime YYYY MM DD HH MM SS GetBuffer 0 lpName szTmp else in UNIX void printTrace LPCSTR lpName LPCSTR lpText char szTmp 4096 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 s n StrCurrentTime YYYY MM DD HH MM SS GetBuffer 0 lpName szTmp endif 應(yīng)修改為 hpp ifdef WIN32 define define vsprintfvsprintf vsprintf vsprintf endif cpp void printTrace LPCSTR lpName LPCSTR lpText char szTmp 4096 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 s n StrCurrentTime YYYY MM DD HH MM SS GetBuffer 0 lpName szTmp 規(guī)則規(guī)則 44 44 宏表達(dá)式的變量應(yīng)使用括號(hào)括 使用宏時(shí)應(yīng)避免傳遞表達(dá)式給宏變量 例 define MAX a b a b a b 應(yīng)書寫為 define MAX a b a b a b 調(diào)用 int nMax MAX i b 應(yīng)書寫為 int nTmpi i int nTmpb b int nMax MAX nTmpi nTmpb 規(guī)則規(guī)則 45 45 單條語句構(gòu)成的宏不應(yīng)使用分號(hào)作為宏結(jié)束 多條語句構(gòu)成宏時(shí) 應(yīng)使用花括號(hào) 括宏體 例 define ThrowExceptionExt sFileName nErrCode sExtMsg ThrowFileExceptionExt FILE LINE sFileName nErrCode sExtMsg return nErrCode define RETCODE n return n 應(yīng)書寫成 define ThrowExceptionExt sFileName nErrCode sExtMsg ThrowFileExceptionExt FILE LINE sFileName nErrCode sExtMsg return nErrCode define RETCODE n return n 規(guī)則規(guī)則 46 46 構(gòu)成宏體的語句必須完成 禁止包含語句塊的部分 例 define CLEAR ALL n for int ii 0 ii n ii CLEAR ALL strlen str str ii 0 define CLEAR ALL n for int ii 0 ii n ii str ii 0 以上兩例應(yīng)書寫為 define CLEAR ALL str n for intint iiii 0 0 ii n ii str ii 0 即使這樣 代碼依然是不安全的 應(yīng)避免在宏中定義變量 規(guī)則規(guī)則 47 47 禁止使用宏替換關(guān)鍵字 如下列為不良寫法 define MYENUM enum MYENUM err E DATE 1 E TIME 2 建議建議 16 16 使用 enum 或 const int 或 inline 函數(shù)代替宏 例 define MAX FRAME SIZE 1024 define ERR DATE 1 define ERR TIME 2 define ERR TASK NO 3 define ExitOnFail if g nErrCode 0 return g nErrCode 應(yīng)書寫為 const int MAX FRAME SIZE 1024 enum ERR TYPE ERR DATE 1 ERR TIME 2 ERR TASK NO 3 inline int ExitOnFail if g nErrCode 0 return g nErrCode 4 44 4變量與常量變量與常量 規(guī)則規(guī)則 48 48 避免使用與全局變量 外部變量同名的局部變量 禁止使用關(guān)鍵字 保留字 函 數(shù)名作為變量名 如下列為不良寫法 例 int nMaxSize 100 intint strlenstrlen 1 for int ii 0 ii 0 n c 應(yīng)書寫為 unsignedunsigned intint c 127 charchar n n 10 while n 0 n c 建議建議 23 23 不要將常量強(qiáng)制轉(zhuǎn)換為變量 有時(shí)可能導(dǎo)致系統(tǒng)崩潰 4 54 5條件判斷條件判斷 規(guī)則規(guī)則 53 53 if 語句的判斷條件必須是邏輯表達(dá)式 不應(yīng)使用 C 默認(rèn)的 0 為 false 非 0 為 true 的規(guī)則 如 例 char p strstr abc a ifif p p 應(yīng)書寫為 char p strstr abc a ifif p p NULL NULL char p str while p while p p 應(yīng)書寫為 char p str while pwhile p 0 0 p for int ii 10 iiii ii 應(yīng)書寫為 for int ii 10 iiii 0 0 ii 規(guī)則規(guī)則 54 54 禁止對(duì)邏輯表達(dá)式進(jìn)行比較操作 如 例 if ii 10 bQuit bQuit TRUE TRUE IsContinue IsContinue FALSEFALSE 應(yīng)書寫成 if ii 10 bQuitbQuit IsContinue IsContinue 規(guī)則規(guī)則 55 55 避免對(duì)浮點(diǎn)類型作等于或不等于判斷 應(yīng)根據(jù)應(yīng)用的實(shí)際情況使用范圍判斷 如 金額的小數(shù)位為兩位 則判斷金額是否為零 可以寫成 if dAmount 0 0001 4 64 6空間申請(qǐng)與釋放空間申請(qǐng)與釋放 規(guī)則規(guī)則 56 56 使用 C 的 new 操作符申請(qǐng)空間 使用 delete 操作符釋放空間 new 申請(qǐng)的數(shù) 組空間 應(yīng)使用 delete 釋放 申請(qǐng)空間后 釋放空間前 應(yīng)判斷指針是否為 NULL 釋放空 間后應(yīng)賦值該指針為 NULL 避免重復(fù)釋放空間 規(guī)則規(guī)則 57 57 盡量在申請(qǐng)空間的函數(shù)內(nèi)部釋放空間 否則應(yīng)妥善傳遞申請(qǐng)的空間指針 并在合 適的時(shí)間釋放 避免內(nèi)存泄漏 4 74 7函數(shù)編寫函數(shù)編寫 規(guī)則規(guī)則 58 58 仔細(xì)選擇函數(shù)的參數(shù)并盡量減少參數(shù)個(gè)數(shù) 沒有參數(shù)時(shí)明確地使用 void 說明 參 數(shù)是數(shù)組類型的 使用數(shù)組類型而非指針類型 參數(shù)是類對(duì)象的 盡量使用對(duì)象的引用或?qū)ο?指針 參數(shù)是大數(shù)據(jù)變量的 必須使用引用或指針 可默認(rèn)值的參數(shù)盡量指定默認(rèn)值 規(guī)則規(guī)則 59 59 函數(shù)入口點(diǎn)應(yīng)檢查每個(gè)參數(shù)的合法性 規(guī)則規(guī)則 60 60 仔細(xì)安排參數(shù)的位置 最常用的參數(shù)放置在最前面 輸入?yún)?shù)盡量放置在左邊 輸出參數(shù)盡量放置在右邊 規(guī)則規(guī)則 61 61 顯式聲明函數(shù)的返回值 沒有返回值的使用 void 說明 返回指針的函數(shù) 使用 NULL 作為錯(cuò)誤返回 禁止返回局部變量的指針或引用 規(guī)則規(guī)則 62