函數設計哲學：單一職責、參數節制、接口極簡——寫出可維護的 C 代碼

編輯：關於C語言

函數是 C 語言面向過程編程的基本構建塊。一個設計優良的函數如同精密儀器：介面清晰、內聚單一、易測易改。本文從工程實踐角度，剖析函數設計的核心原則、常見反模式與重構指南。

核心原則：一個函數只做好一件事

單一職責：函數名即契約，parse_json 只解析，不下載、不寫文件、不打印日誌。
可讀性優先：函數體應在一屏內顯示完整 (≤50 行)，無需翻頁。
參數節制：參數 ≤ 3 個；超過則封裝為結構體 Config / Context 傳指針。

反模式 1：超長參數列表

// ❌ 9 參數：調用極易誤序、漏傳、擴展困難
void vMErrReport(
    SINT4 vlSrvId, SINT2 vnErrLevel, SINT8 vnErrPos,
    const SCHAR* vsapModuleName, const SCHAR* vsapFileName,
    const SCHAR* vsapErrTitle, const SCHAR* vsapErrDetail,
    SINT4 vlReturnVal, SINT4 vlSysError
);

// ✅ 重構：參數對象模式
typedef struct {
    int srv_id;
    int err_level;
    long err_pos;
    const char *module;
    const char *file;
    const char *title;
    const char *detail;
    int ret_val;
    int sys_err;
} ErrReportCtx;

void report_error(const ErrReportCtx *ctx);  // 單一指針，擴展不破壞調用點

反模式 2：循環中重複昂貴計算

// ❌ 每次迭代調用 strlen
for (int i = 0; i < strlen(s); ++i) putchar(s[i]);

// ✅ 提取不變量
size_t len = strlen(s);
for (int i = 0; i < len; ++i) putchar(s[i]);

反模式 3：過度依賴全局狀態

// ❌ 隱式依賴全局緩衝區，不可重入、難測試
char g_buf[1024];
void format_msg(int code) { sprintf(g_buf, "ERR_%d", code); }

// ✅ 顯式傳遞輸出緩衝區
void format_msg(int code, char *buf, size_t sz) {
    snprintf(buf, sz, "ERR_%d", code);
}

接口設計檢查清單

維度	優良實踐	違規信號
命名	動詞短語：`calculate_crc32`	名詞、縮寫、過於通用 `process`
參數	輸入 `const`、輸出指針、上下文結構體	>3 參數、無 `const`、混雜輸入輸出
返回	狀態碼 / 結果指針 / 結構體	全局變量、錯誤碼混雜業務值
副作用	文檔明確標註 (修改參數/IO/鎖/內存)	隱式修改全局/靜態變量
錯誤處理	返回錯誤碼、輸出參數帶回詳情、不直接 exit	調用 `abort/exit`、忽略返回值
可測試性	無靜態/全局依賴、依賴注入	耦合單例、硬編碼路徑

進階模式：函數指針實現策略/回調

typedef int (*CmpFunc)(const void*, const void*);

void generic_sort(void *base, size_t n, size_t sz, CmpFunc cmp) {
    // 通用排序邏輯，cmp 注入比較策略
}

// 使用
int cmp_int(const void *a, const void *b) { ... }
generic_sort(arr, n, sizeof(int), cmp_int);