1、文檔編號產品版本受控狀態DC-SB-2003-1005V 1.0內部產品名稱： 軟件編程規范共 頁軟件編程規范( 僅供內部使用 )北京世紀百合科技有限公司Beijing Centurial Lily Technology Co.,Ltd.版權所有不得復制北京世紀百合技術有限公司軟件編程規范第 2 頁 共 24頁文檔修改記錄版本號日期所改頁注 記提交人批準人北京世紀百合技術有限公司軟件編程規范第3頁共24頁目 錄1.引言.41.1目的 .41.2范圍 .42.規范.42.1文件 .42.2版面風格 .82.3標識符命名 .122.4函數與宏 .142.5代碼的可靠性 .183.附錄：通用類型的公

2、共定義 .23北京世紀百合技術有限公司軟件編程規范第 4 頁 共 24頁1. 引言1.1目的本規范的目的在于增加源代碼的可讀性，減少程序員對代碼理解上的偏差，使程序員能夠編寫出可靠的代碼，降低代碼維護成本。1.2范圍本規范內容涉及范圍包括：文件、版面、注釋、標識符、變量和結構、函數、宏以及可理解性等。本規范適用于公司開發的所有軟件產品。在新軟件的編碼過程中本規范必須執行。2. 規范2.1文件2.1.1頭文件的名稱一律為小寫，格式為“子系統名_ 文件名 .h ”。例如：ipf_protocol.h 等。2.1.2頭文件的格式如下：? 注釋頭，格式參見軟件編程規范；? 頭文件預編譯開關開始，格式為

3、：#ifndef 預編譯開關 #define 預編譯開關其中預編譯開關格式為：“ _文件名 _H”，其中文件名一律大寫? 頭文件內容；? 頭文件預編譯開關結束，格式為：#endif用來和頭文件預編譯開關的開始對應。例如：以下為 ipf_ip.h 頭文件的內容：/*Copyright (c) Lily Of The Century Technology Co., LTD.ALL RIGHTS RESERVEDDescription:/用于詳細說明此程序文件完成的主要功能*/#ifndef _IPF_IP_H#define _IPF_IP_H.北京世紀百合技術有限公司軟件編程規范第 5 頁 共 2

4、4頁<頭文件正文 >.#endif2.1.3頭文件的定義要有層次，禁止交叉引用。說明：頭文件的層次設置為公共模塊、私有模塊。頭文件的引用次序為下層頭文件引用上層頭文件、私有頭文件引用公共頭文件，聲明結構時尤其要注意，不允許出現交叉引用的情況。示例：如下定義不符合規范頭文件 isdn_a.h/*Copyright (c) Lily Of The Century Technology Co., LTD.ALL RIGHTS RESERVEDDescription:定義配置數據結構*/#ifndef _ISDN_A_H#define _ISDN_A_H#include“isdn_b.h”

5、typedef struct.;ISDN_CONTROL stIsdnControl;.;ISDN_ CONFIG;#endif頭文件 isdn_b.h/*“isdn_a.h北京世紀百合技術有限公司軟件編程規范第 6 頁 共 24頁Copyright (c) Lily Of The Century Technology Co., LTD.ALL RIGHTS RESERVEDDescription:定義控制數據結構*/#ifndef _ISDN_B_H#define _ISDN_B_H#include”typedef struct.;ISDN_CONFIG stIsdnConfig;.;ISD

6、N_CONTROL;#endif為了解決上述矛盾，可以將兩個結構合并到一個文件中聲明。2.1.4文件中如果引用系統頭文件，必須使用“ <“和“ >“；如果引用自定義的頭文件，必須使用“ ”“和“ ”“。說明：系統頭文件是指由編譯系統提供的頭文件。示例：如下書寫不符合規范。#include“stdlib.h”#include <isdn_config.h>應該改作：#include <stdlib.h>#include“isdn_config.h”2.1.5頭文件中只能聲明變量類型，禁止定義變量。說明：如果在頭文件中定義變量，當有多個源文件引用該頭文件時，會出

7、現重復定義的錯誤。示例：如下頭文件是不規范的。頭文件 isdn_a.h/*北京世紀百合技術有限公司軟件編程規范第 7 頁 共 24頁Copyright (c) Lily Of The Century Technology Co., LTD.ALL RIGHTS RESERVEDDescription:定義配置數據結構*/#ifndef _ISDN_A_H#define _ISDN_A_Htypedef struct.;ISDN_ CONFIG;ISDN_CONFIG g_stIsdnConfig;#endif結構變量 g_stIsdnConfig 不能在頭文件中定義，只能在源文件中定義。可以在

8、相應的源文件定義后，頭文件作如下改動：ISDN_CONFIG g_stIsdnConfig;改為extern ISDN_CONFIG g_stIsdnConfig;2.1.6頭文件的聲明順序，應該有層次感。說明：頭文件的聲明順序一般是宏、結構、函數、變量。函數在頭文件中聲明時開頭可以不加“ extern”2.1.7 源文件名稱一律小寫，格式為：子系統名 _文件名 .c，示例： ipf_ pkt.c 表示在 IPF 子系統的包處理文件。2.1.8源文件必須加注釋頭。源文件注釋頭格式為：/*Copyright (c) Lily Of The Century Technology Co.,LTD.A

9、LL RIGHTS RESERVEDDescription:/用于詳細說明此程序文件完成的主要功能*/北京世紀百合技術有限公司軟件編程規范第 8 頁 共 24頁2.2版面風格2.2.1程序塊采用縮進風格編寫，縮進使用TAB符號， TAB符號規定為4 個空格。變量說明之后必須加空行。說明：由開發工具自動生成的代碼例外。示例：如下例子不符合規范。void isdn_InitConfig(void)WORD wConfigNumner;.; /program code應如下書寫void isdn_InitConfig(void)WORD wConfigNumner;.; /program code2

10、.2.2不允許把多個短語句寫在一行中，一行只寫一條語句。示例：如下例子不符合規范。wLength = wWidth = 0;或 wLength = 0, wWidth = 0;應如下書寫wLength = 0;wWidth = 0;禁止如下寫法：int i = j = 0;或 int i = 0,j = 0;應該寫作：int i = 0;int j = 0;或int i,j;i = 0;j = 0;2.2.3do、 while 、 switch 、 case、 default 、 if 、 else、 for等語句自占一行，且if 、 else語句在同一列。示例 1：如下例子不符合規范。do

11、.; /program code while (pstUser != NULL);應如下書寫：do北京世紀百合技術有限公司軟件編程規范第 9 頁 共 24頁.; /program code while (pstUser != NULL);示例 2：如下例子不符合規范。while (pstUser != NULL) .; /program code應如下書寫：while (pstUser != NULL).; /program code示例 3：如下例子不符合規范。switch (dwCounter) case 1: dwCounter+;.; /program codebreak;defaul

12、t:break;應如下書寫：switch (dwCounter)case 1:dwCounter+;.; /program codebreak;default:break;示例 4：如下例子不符合規范。if (pstUser = NULL) return;else .; /program code應如下書寫：if (pstUser = NULL)return;else.; /program code示例 5：如下例子不符合規范。for (i = 0;i < 10;i+) .; /program code應如下書寫：for (i = 0;i < 10;i+)北京世紀百合技術有限公司軟

13、件編程規范第 10 頁 共 24頁.; /program code2.2.4函數的開始、結構的定義及循環、判斷等語句中的代碼都要采用縮進風格。示例：如下例子不符合規范。int isdn_Config(void).; / program codereturn 0;應該改為int isdn_Config(void).; / program codereturn 0;示例：如下例子不符合規范。typedef structWORD wSlot;WORD wPort;ISDN_CONFIG;應該改為typedef structWORD wSlot;WORD wPort;ISDN_CONFIG;2.2.5

14、在 switch 的處理程序塊中， case 和 default 語句下的處理語句也要遵從語句縮進要求。示例：以下寫法是不規范的switch (wEvent)case 1:.; /program codebreak;北京世紀百合技術有限公司軟件編程規范第 11 頁 共 24頁應該改為：switch (wEvent)case 1:.; /program codebreak;default:break;2.2.6程序塊的分界符（大括號 '' 和 '' ）應各獨占一行并且位于同一列，同時與引用它們的語句左對齊。示例：如下例子不符合規范。if (.). / progra

15、m codevoid isdn_ExampleFun( void ) . / program code應如下書寫。if (.). / program codevoid isdn_ExampleFun( void ).; / program code2.2.7函數頭部應進行注釋，列出：函數的名稱、功能、輸入參數、輸出參數、返回值等。示例：編寫函數時候按照下面這段注釋編寫。/*Func Name:/ 函數名稱Description:/ 函數功能的描述Input:/ 輸入參數說明Output:/ 對輸出參數和函數返回值的說明*/北京世紀百合技術有限公司軟件編程規范第 12 頁 共 24頁2.2.8注

16、釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方（對單條語句的注釋）相鄰位置，不可放在下面。示例：如下例子不符合規范。isdn_Init();/ 初始化 ISDN 任務應如下書寫：/ 初始化 ISDN 任務isdn_Init();2.2.9 對有實際含義的變量或者常量的注釋，應放在其上方相鄰位置或右方。對(包宏的注釋，應放在上面，不可放在其右方或下方。對數據結構的聲明括數組、結構、類、枚舉等)，注釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的注釋放在此域的右方。示例：以下寫法不規范#define ERROR_MSG_ON /錯誤信息打印輸出開關應改為/ 錯誤信息打印輸出開關#d

17、efine ERROR_MSG_ON2.2.10 允許使用 ”/”進行注釋示例：以下注釋是允許的/ 根據 CFM 所存的配置信息更新接口配置信息void isdn_SetConfigData(void).; /program code2.3標識符命名2.3.1局部變量采用大小寫混排的匈牙利方式命名，命名格式為前綴+變量名稱，其中變量名由一個或一個以上的單詞組成，每個單詞首字母大寫，其余一律小寫。說明：前綴要表明變量類型。下表為定義變量時候使用的前綴。類型前綴類型名稱BOOLEANb布爾型BYTEby無符號字符型WORDw無符號短整型DWORDdw無符號長整型charc字符型shorts短整型i

18、nti整型北京世紀百合技術有限公司軟件編程規范第13頁共24頁longl長整型st結構類型un聯合類型p指針pbyBYTE 的指針pwWORD 的指針pdwDWORD 的指針pst結構的指針pun聯合的指針pa數組的指針pfn函數指針pm消息的指針pc字符型的指針ps短整型的指針pi整型的指針pl長整型的指針pp(根據類型添加其他前綴 )指針的指針a數組abyBYTE 數組awWORD 數組adwDWORD 數組ast結構數組aun聯合數組afn函數數組ac字符型數組as短整型數組ai整型數組al長整型數組sz以 null 結尾的字符串型注：類成員變量前應加前綴m_ ;示例： 以下的書寫不規范

19、WORD slot;BYTE *byAccess;DWORD arp_frame_count;應該寫作：WORD wSlot;BYTE *pbyAccess;DWORD dwArpFrameCount;2.3.2普通宏的定義使用全大寫字母加下劃線的方式，結構為：子系統 +下劃線 + 宏內容名稱。示例：北京世紀百合技術有限公司軟件編程規范第14頁共24頁#define IP_MAX_HWA_LEN6#define IP_VER(x)(x >>4) & 0xF0)2.3.3函數的命名為：前綴 +下劃線 +字符串。其中前綴為全小寫的子系統名稱，字符串由一個或多個單詞組成，每個單詞

20、首字母大寫，其他字母小寫。示例：void MsgCreate(void);void icmp_PktRecv(void);2.3.4調試用的編譯開關是開頭為下劃線的全大寫字符串，具體格式是：下劃線+DEBUG+ 子系統名稱 +下劃線 +名稱。示例： _DEBUG_IPF_IP_PACKET、_DEBUG_TCP_OPTION等。2.3.5結構聯合類型命名規則為：子系統名稱+下劃線 +結構名稱、子系統名稱+下劃線 +聯合名稱，其中所有字母大寫。示例：typedef struct.;IP_TRACEROUTE;typedef union.;ICMP_PKT ;2.3.6全局變量命名的具體格式是：前

21、綴+下劃線 +子系統名 +下劃線 +字符串，其中前綴為小寫的“ g”，子系統名稱全部小寫，字符串由一個或多個單詞組成，每個單詞首字母大寫，其他字母小寫。示例： g_icmp_TraceRouteQueue 、g_ospf_InterfList 等。2.3.7消息宏定義的采用一下格式：前綴+下劃線 +字符串 +下劃線 +后綴。其中前綴采用小寫的“ mm”，字符串標記消息宏的具體含義，由一個或多個單詞組成，每個單詞首字母大寫，其他字母小寫，后綴為XXXtoYYY ，表示消息的傳送方向， XXX 表示源子系統名， YYY為目的子系統名，全部用大寫字母表示。示例： mm_AddRoute_BGPtoR

22、TMGT表示從 BGP 協議發送到路由管理實體的增加一條路由的消息， mm_ShowIpRoute_CLItoRTMGT表示從 CLI 發送到路由管理子系統的要求顯示路由表的消息。2.4函數與宏2.4.1對函數的返回值要仔細、全面地處理。說明：對提供返回值的函數，尤其是接口函數，其返回值必須檢查。示例：以下函數是不規范的。北京世紀百合技術有限公司軟件編程規范第 15 頁 共 24頁void isdn_SendMessage(void).; /program codeMsgPost(.); /發送消息應該改作void isdn_SendMessage(void)INT32 iPost;.; /p

23、rogram codeiPost = MsgPost(.); /if (iPost = OK)發送消息.; /處理代碼else.; /處理代碼2.4.2接口函數的輸入參數（尤其是指針和數組下標）、非輸入參數的合法性必須檢查。說明：函數的輸入主要有兩種：一種是參數輸入；另一種是非參數輸入，包括全局變量、數據文件等，這些參數都需要作檢查。示例：下函數的實現不符合規范。RESULT isdn_Receive(NI_CELL *pstCell,SK_BUF *pstSkBuf).; /接收數據代碼return OK;應改作以下寫法。RESULT isdn_Receive(NI_CELL *pstCel

24、l,SK_BUF *pstSkBuf)if (pstCell = NULL) | (pstSkBuf = NULL)return FALSE;.; /接收數據代碼return OK;北京世紀百合技術有限公司軟件編程規范第 16 頁 共 24頁2.4.3禁止把函數的參數作為工作變量。說明：需要做改變的參數，應該先用局部變量代之，最后再將該局部變量的內容賦給該參數。示例：下函數的實現不符合規范。BOOLEAN isdn_SumData(WORD wNumber,WORD *pwData, WORD *pwSum)WORD wCount;if (pwData = NULL) | (pwSum = N

25、ULL)return FALSE;*pwSum = 0;for (wCount = 0; wCount < wNumber; wCount+)*pwSum += pwDatawCount; / pwSum成了工作變量，不規范return TRUE;應改作以下寫法。BOOLEAN isdn_SumData(WORD wNumber,WORD *pwData, WORD *pwSum)WORD wCount;WORD wSumTemp;if (pwData = NULL) | (pwSum = NULL)return FALSE;wSumTemp = 0;for (wCount = 0; w

26、Count < wNumber; wCount+)wSumTemp += pwDatawCount;*pwSum = wSumTemp;return TRUE;2.4.4對于沒有參數的函數，要定義為void 。說明：目的減少函數間接口的復雜度。示例：如下函數寫作不規范BOOLEAN isdn_Init().; /program codereturn TRUE;北京世紀百合技術有限公司軟件編程規范第 17 頁 共 24頁應改作：BOOLEAN isdn_Init(void).; /program codereturn TRUE;2.4.5明確函數的返回值，當函數不需要返回值時要定義為voi

27、d 。示例：如下函數寫作不規范isdn_InitCtrlBlock(void).; /program code應改作：void isdn_InitCtrlBlock(void).; /program code2.4.6用宏定義表達式時，要使用完備的括號。示例：如下定義的宏都存在一定的風險，不符合規范。#define MAX(a,b) a > b ? a : b#define MAX(a,b) (a > b ? a : b)#define MAX(a,b) (a) > (b) ? (a) : (b)正確的定義應為：#define MAX(a,b) (a) > (b) ?

28、(a) : (b)2.4.7將宏所定義的多條表達式放在大括號中。示例：下面的定義不規范#define ISDN_INIT_VALUE(a, b) a = 0;b = 0;正確的用法應為：#define ISDN_INIT_VALUE(a, b) a = 0;b = 0;2.4.8使用宏時，不允許參數發生變化。示例：如下用法導致錯誤。#define MAX(a, b)(a) > (b) ? (a) : (b)iResult = MAX(iRx+,iTx);將被預處理器解釋為iResult = (iRx+) > (iTx) ? (iRx+) : (iTx);此時如果輸入iRx = 6;

29、北京世紀百合技術有限公司軟件編程規范第18頁共24頁iTx = 5;代碼執行結果iResult = 7，此時iRx為 8 。應該改作如下用法：iResult = MAX(iRx,iTx);iRx+;2.5代碼的可靠性2.5.1系統運行之初，要初始化所有本系統的全局變量，禁止未經初始化的全局變量被引用。說明：使用未初始化的數據，容易使系統進入混亂狀態。示例：以下的全局變量如果沒有在系統運行時初始化，在被函數使用時會出錯ISDN_CELL *g_pstIsdnCellISDN_MAX_CELL_NUM; void isdn_ShowChannel(WORD wSlot,WORD wPort) IS

30、DN_CELL *pstIsdnCell = 0;int i;for (i = 0; i < ISDN_MAX_CELL_NUM;i+)if (g_stpIsdnCelli != NULL)pstIsdnCell = g_pstIsdnCelli;/ 如果 g_pstIsdnCell沒有初始化為空，以下語句會出錯if (pstIsdnCell->wSlot = wSlot) && (pstIsdnCell->wPort = wPort)break;.; /other program code北京世紀百合技術有限公司軟件編程規范第 19 頁 共 24頁2.5.2

31、申請內存之后，應該立即檢查指針值是否為 NULL？（防止使用指針值為NULL的內存）說明：申請內存時，如果申請失敗，應該避免使用該指針。必須使用if (p = NULL)或 if (p != NULL)進行防錯處理。2.5.3禁止將未被初始化的內存作為零值使用。說明：創建的數組或動態申請的內存，其初始值是不確定的，不能當作零處理。示例：以下代碼是不規范的。void isdn_CheckIe(BYTE *pbyIe,WORD wIeLen)WORD wTempLen;/wTempLen 未初始化，其初始值不一定為 0 while(wTempLen < wIeLen) .; /other p

32、rogram codewTempLen += 2;應作如下改寫：void isdn_CheckIe(BYTE *pbyIe,WORD wIeLen)WORD wTempLen;wTempLen = 0;while (wTempLen < wIeLen).; /other program codewTempLen += 2;北京世紀百合技術有限公司軟件編程規范第 20 頁 共 24頁2.5.4動態內存的申請與釋放要配對，防止內存泄漏。說明：內存泄漏問題要高度重視。內存泄漏會引起系統死機或崩潰，一般在系統啟動很長一段時間后才發作，不易察覺，一般的測試手段也檢測不到。2.5.5內存的申請和釋放

33、應該使用函數malloc( )和 free( )說明：內存的申請和釋放應該使用函數malloc( )和 free( )，或使用delete( )函數（特殊需求的系統函數除外）。絕對禁止malloc( )和new( ) 和 free( )混用，否則會引起任務掛起等系統錯誤。new( ) 和delete( )、示例：如下寫法是絕對禁止的。void isdn_ShowRunning(void)BYTE *pbyData;pbyData = (BYTE *)malloc();if (pbyData = NULL)return;.; /programm codedelete(pData); /mallo

34、c與delete混用return;應該改作如下書寫：void isdn_ShowRunning(void)BYTE *pbyData;pbyData = (BYTE *)new BYTE;if (pbyData = NULL)return;.; /programm codefree(pbyData);return;北京世紀百合技術有限公司軟件編程規范第 21 頁 共 24頁2.5.11 防止引用已經釋放的內存空間或未初始化的指針變量。函數中分配的內存，如果以后不再使用，在退出函數前應該釋放。示例：下函數在退出之前，沒有把分配的內存釋放。int ExampleFunction(BYTE byLe

35、n)BYTE *pbyBuf;pbyBuf = (BYTE *)malloc(MAX_LENGTH);.; /program code, include check pBuf if or not NULLif (byLen > MAX_LENGTH)return LENGTH_ERROR; /忘了釋放 pbyBuf.; / other program code應改為如下。int ExampleFunction(BYTE byLen)BYTE *pbyBuf;pbyBuf = (BYTE *)malloc(MAX_LENGTH);.; /program code, include chec

36、k pBuf if or not NULLif (byLen > MAX_LENGTH)free(pBuf); /退出之前釋放pbyBufreturn LENGTH_ERROR;.; / other program code2.5.12 在 switch 的處理程序塊中，必須有default 語句；并且每個case 語句都要有對應的 break 。說明：如果一個case下的處理語句需要調用下一個case的處理語句，可以將下一個 case的處理語句 copy 過來。示例：以下寫法是不規范的switch (wEvent)case 1:isdn_SendEvent(wEvent);北京世紀百合技術有限公司軟件編程規范第 22 頁 共 24頁case 2:wEvent+;break;default