C語言頭文件組織最佳實踐：模組化、封裝與大型專案架構

核心原則：介面與實現分離

• .h 僅暴露介面：宏、類型定義、函數聲明、extern 變量聲明
• .c 包含實現：函數定義、內部變量定義（static 限制作用域）
• 嚴禁在 .h 中放置可執行代碼或數據定義

推薦的三層頭文件架構

1. 全域變量集中管理

// Globals.h - 唯一聲明入口
#ifndef GLOBALS_H
#define GLOBALS_H
extern int g_speed;
extern int g_torque;
#endif

// Globals.c - 唯一定義入口
#include "Globals.h"
int g_speed = 0;
int g_torque = 0;

各模組 #include "Globals.h" 即可安全使用，避免重複定義與分散聲明。

2. 模組專用頭文件

// math.h - 公開介面
#ifndef MATH_H
#define MATH_H
#ifdef __cplusplus
extern "C" {
#endif
int add(int a, int b);
double calc_pi(void);
#ifdef __cplusplus
}
#endif
#endif

// math.c - 實現與私有內容
#include "math.h"
#include "Globals.h"   // 需要全域變量時
static double pi_cache = 0;  // 私有，不暴露
int add(int a, int b) { return a + b; }

3. 專案主頭文件（可選）

僅包含專案級配置宏、通用類型定義，不包含具體模組頭文件，減少編譯依賴。

頭文件編寫鐵律（必讀）

1. 防重複包含：#ifndef MODULE_H / #define MODULE_H / ... / #endif
2. 無實現代碼：無函數體、無變量定義（const/static 除外）
3. 無私有內容：模組內部函數/變量以 static 限定在 .c 中
4. 最小依賴：.h 僅包含必要的其他 .h，優先前向聲明
5. C++ 兼容：extern "C" 包裹函數聲明
6. 文檔化介面：每個公開函數/變量附 Doxygen 註解
7. 版本穩定：發布後介面不破壞兼容，新增功能增新頭文件

.c 文件組織規範

• 首行 #include "module.h"（自我檢測介面完整性）
• 其次系統頭文件、再專案頭文件
• 內部函數/變量全加 static
• 嚴禁在 .c 中使用 extern（除非引用無頭文件的舊代碼）
• 匯編文件同樣提供 .h 暴露符號

大型專案擴展模式