《編碼checklist規範》--學習筆記

1. 排版

圖片網址

2. 註釋

• 函數頭註釋範例

/** * 發送數據給服務器 * @param [in]buf 數據緩衝區指針 * @param len 數據長度 * @return <0 表示失敗，不然表示實際發送成功的字節數 * @sample * int len = send_buf(buf, buflen); * if (len < 0) { * DUMP("send failed, errno: %x\n", len); * return -1; * } else { * DUMP("send ok, already send %d bytes.\n", len); * } */
int send_buf(const char* buf, int len);

• 文件頭註釋範例

/* 功能：本文件定義文件列表的接口，文件列表是個存儲文件路徑名和文件信 息的列表，本文件提供了文件列表的存儲、讀取、定位、訪問等接口。 日期：2011-3-4 做者：zbc */
#ifndef FILELIST_H_
#define FILELIST_H_
…
#endif //FILELIST_H_

• 類型定義註釋

/** * 文件列表類 * @remark * 可用於記錄系統所緩存的全部小文件，該列表可存在磁盤上 * @note */
class filelist {
...
};

• 全局變量註釋

char g_log_fname[MAX_PATH]; //日誌文件的路徑名稱，從配置文件中讀取獲得
//日誌文件的路徑名稱，從配置文件中讀取獲得
char g_log_fname[MAX_PATH];

• 宏註釋

/** * 釋放內存，並把指針清零，防止重複釋放 * @param ptr 內存塊指針，只容許傳入 malloc/remalloc/strdup 等 * C 庫函數分配的內存塊指針 */
#define FREE_ZERO(ptr) \
do{                    \
if (!(ptr)) {          \
free(ptr);             \
ptr = NULL;            \
}                      \
}while(0)
// 最大的緩衝區長度
#define MAX_BUF_SIZE 200

• 語句註釋

-----------
// 將全部用戶配置文件打包
pdir = opendir("/var/sangfor");
if (!pdir) {
...
return -1;
}
// 遍歷/var/sangfor 目錄下全部配置文件(*.conf)，經過 tar 命令將其打到壓縮包
while ((pcur = readdir(pdir)) != NULL) {
...
}

圖片連接

3. label - - 標識符

• 一個變量多個用途：一個實際引發了 BUG 的例子：value 既做爲入參表示哈希值，又做爲出參，表示是否成功

#define HASH_INSERT(hash_table, node, value, type) \
do {                                                   \
    node->pre = NULL;                                  \
    node->pnext = NULL;                                \
    unsigned int h_i_i = value % HASH_SIZE;            \
    if (hash_table[h_i_i] != NULL &&                   \
        hash_table[h_i_i]->key != node->key) {         \
        ...                                            \
    }else if (hash_table[h_i_i] == NULL) {             \
        hash_table[h_i_i] = node;                      \
    } else {                                           \
        value = 0;                                     \
    }                                                  \
} while (0);

• 提供給 c 模塊使用的函數原型聲明

#ifdef __cplusplus
extern "C" {
#endif
void foo(int xxx, int yyy);
#ifdef __cplusplus
}
#endif

圖片連接

4. 函數

• 如下函數聲明違反 checklist

1) void func(string name)；
2) struct record {
int type;
int len;
char data[16];
};
void send_record(record rec);

• 函數參數中使用布爾類型，會使代碼更難以理解，如

UpdateData(TRUE)
CreateProcess(chPath, "", NULL, NULL, FALSE, 0, NULL, NULL, &si, &pi)
若是不是對這些函數很是熟悉，你知道這些 TRUE，FALSE 表明什麼意思嗎？如 果 改 爲
 UpdateData(SAVE_VALIDATE) ， 
 CreateProcess(chPath, "", NULL, NULL,NO_INHERIT_HANDLE, 0, NULL, NULL, &si, &pi)
改造方法：
UpdateData 是 MFC 函數，原型以下：
BOOL UpdateData(BOOL bSaveAndValidate);
下述修改方法均可以提升 UpdateData 的可讀性：
1）分拆成兩個函數實現
BOOL UpdateData();
BOOL UpdateData_SaveAndValidate();
2）將 bSaveAndValidate 參數改形成枚舉
enum SaveAndValidate_e{
SAVE_VALIDATE,
NO_SAVE_VALIDATE
};
BOOL UpdateData(enum SaveAndValidate_e eSave);
這樣，在調用這個函數時就有一個名字了,能夠經過枚舉的名字更好的理解這個函數調用的意思，
如：UpdateData(SAVE_VALIDATE);

• 以上代碼違反子條款 3，sizeof(arr)的結果爲 sizeof(int)

void test_arr_copy(int arr[ARRAY_SIZE])
{
    int buf[ARRAY_SIZE];
    memcpy(buf, arr, sizeof(arr));
}

• 非 GCC 編譯環境的處理方法

vc 等編譯器不支持__attribute__擴展編譯指令。爲了保證代碼的跨平臺能力，能夠在非 GCC 編譯
環境下加上以下代碼：
#if !defined(__GNUC__)
#define __attribute__(x)
#endif
這樣能夠保證使用了__attribute__擴展編譯選項的代碼可以順利在 VC 下編譯

• format 指令的參數該怎麼定

Format 指令有三個參數：format(printf,fmt_pos,args_pos)，此處固定第一個參數爲 printf，第二
個參數爲格式串參數在函數參數列表中的位置（位置計數從 1 開始），第三個參數爲變參開始的位置。
如：
void my_print(int fd, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
表示聲明 my_print 爲類 printf 函數，my_print 的第二個參數爲格式串，變參列表從第三個參數開始。

• 成員函數

若是類 printf 函數是一個類的成員函數，format 指令中的位置參數必須加 1（即把 this 做爲該函
數的第一個參數），如：
class strings {
void print(int fd, const char *fmt, ...) __attribute__((format(printf,3,4)));
};

圖片連接

5. 宏定義

圖片連接

6. 結構體

圖片連接

7. 語句

圖片連接

8. 錯誤處理

圖片連接