您现在的位置：程式碼之家 >> 編程語言 > >> C語言 >> C++ >> 關於C++

軟體工程模組化規範：函數設計、介面管理與錯誤處理體系

編輯：關於C++

為提升軟體重用性、可讀性與維護性，建立嚴謹的模組化開發規範至關重要。本文整理自實務專案經驗，涵蓋函數規模控制、重複代碼消除、介面設計原則、分層重構範例，並提供完整的錯誤代碼體系 (HRESULT 風格) 與函數模板範本，可直接套用於團隊開發標準。

四大模組化核心規範

函數精簡：單一函數不超過 150 行。超過需申請複審，並補充詳細註解與設計文件。
三次法則：相同功能第三次出現即須重構為通用函數，發布介面文件並備案。
優先重用：開發前檢索現有模組，避免重複造輪子。
分層解耦：新增功能時調整原有函數層次，消除重複代碼。高層函數呼叫低層通用函數，而非複製貼上。

分層重構實戰範例

重構前：cmGetSomething 內含開檔、讀取、關檔邏輯。新需求需支援傳入已開啟的 CFile*。

重構後：

// 低層通用讀取函數
long cmReadSomething(CFile* pFile) {
    if (!pFile) return CM_POINTER_IS_NULL;
    // 核心讀取邏輯...
    return CM_OK;
}

// 高層封裝：開檔 → 呼叫低層 → 關檔
long cmGetSomething(const char* pszFileName) {
    CFile* pFile = new CFile(pszFileName, CFile::modeRead);
    if (!pFile) return CM_POINTER_IS_NULL;
    long lResult = cmReadSomething(pFile);
    IF_ERROR_GOTO_END; // 巨集：失敗跳轉 END
    delete pFile;
END:
    return lResult;
}

關鍵點：核心邏輯下沉，高層僅負責資源獲取/釋放與錯誤傳遞。

介面設計五大原則

介面優先：先定介面 (函數簽名、參數語意)，再寫實作；定義後凍結，避免頻繁變更。
最小驚訝：參數語意單一，輸入/輸出分離，錯誤碼不混雜於業務參數。
全域變數即介面：能不用全域變數就不用；必須用時在模組開頭明確宣告並說明。
追求「永遠成功」：函數內部處理可預期錯誤，呼叫端無需檢查即可安全使用（如內部重試、預設值）。
文件同步：介面變更同步更新標頭檔註解與開發手冊。

統一錯誤代碼體系 (makehresult.h)

採用 COM 風格 HRESULT 結構：Severity(1) | Customer(1) | Reserved(1) | Facility(11) | Code(16)。

// 設施代碼
#define FACILITY_CM   0x80  // 通用模組
#define FACILITY_VR   0x81  // 虛擬實境
#define FACILITY_IMG  0x82  // 影像處理

// 類別代碼 (高 6 bits)
#define MEMORY_CLASS  0x01
#define FILE_CLASS    0x02

// 錯誤碼產生巨集
#define CMEMAKEHR(code) MAKE_HRESULT(SEVERITY_ERROR, FACILITY_CM, (0x38<<10)|code)

// 常用錯誤碼
#define CM_OK                    S_OK
#define CM_MEM_ALLOC_FAIL        CMEMAKEHR(0x001)
#define CM_INVALID_POINTER       CMEMAKEHR(0x003)
#define CM_OPEN_FILE_FAIL        CMEMAKEHR(0x011)
#define CM_READ_FILE_FAIL        CMEMAKEHR(0x017)
#define CM_PARAM_BEYOND          CMEMAKEHR(0x030)
#define CM_CONNECT_FAIL          CMEMAKEHR(0x700)
// ... 更多定義見原文

錯誤處理輔助巨集與訊息對應表

// 自動檢查並跳轉
#define IF_ERROR_GOTO_END if (FAILED(lResult)) goto END;

// 運行時顯示中文/英文訊息
static RESULTINFOS sResultInfo[] = {
    {CM_MEM_ALLOC_FAIL, "記憶體配置失敗", "Memory Alloc Failed"},
    {CM_OPEN_FILE_FAIL, "檔案開啟失敗", "Open File Failed"},
    // ...
};
void DisplayChineseMessage(HRESULT hr) {
    MessageBox(NULL, GetChineseMessage(hr), "錯誤", MB_OK);
}