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

核心原則：.h 只放聲明，.c 只放定義

頭文件是模塊的公共接口契約，源文件是私有實現細節。嚴格分離才能實現低耦合、高內聚。

方案一：傳統模塊自帶全局變量 (不推薦大型專案)

// mymath.h
#ifndef MYMATH_H
#define MYMATH_H
extern int Global_A;        // 聲明全局變量
extern void fun(void);      // 聲明接口函數
#endif

// mymath.c
#include "mymath.h"
int Global_A;               // 定義全局變量
void fun(void) { ... }      // 實現

缺點：全局變量散落各模塊，難以追蹤、易衝突、破壞封裝。

方案二：統一全局變量管理 (推薦)

// Globel_Var.h  —— 唯一全局變量聲明處
#ifndef GLOBAL_VAR_H
#define GLOBAL_VAR_H
extern int speed;
extern int torque;
// ... 所有跨模塊共享變量
#endif

// Globel_Var.c  —— 唯一全局變量定義處
#include "Globel_Var.h"
int speed;
int torque;

使用時：

// aa.h
#include "Globel_Var.h"
extern void fun(void);

// aa.c
#include "aa.h"
void fun(void) { speed = 100; } // 直接用

// bb.c
#include "bb.h"
#include "aa.h" // 間接包含 Globel_Var.h
void fun_1(void) { fun(); torque = 200; }

優勢：單一真實來源，易審計、易重構、避免重複定義錯誤。

頭文件編寫鐵律 (必須遵守)

1. 無可執行代碼、無數據定義：只能有宏、類型定義、extern 聲明。
2. 無私有內容：模塊內部用的函數/變數/宏/類型，留在 .c 文件開頭 static 修飾。
3. 防重複包含：#ifndef MODULE_H #define MODULE_H ... #endif 或 #pragma once。
4. 自給自足：頭文件內部包含其依賴的其他頭文件，使用者無需額外包含。
5. 穩定接口：發布後盡量不改 .h，改也要向後兼容。

接口頭文件進階規範 (大型專案)

1. 一模塊一接口：abc.c 對應 abc.h。
2. 慎用 extern 變量：優先提供 get_xxx()/set_xxx() 訪問函數，保護數據不變量。
3. 最小化依賴：.h 中盡量不 #include 其他模塊的接口頭文件，除非參數/返回值需完整類型定義。前向聲明 struct Foo; 即可用於指標參數。
4. 不包含僅執行文件用的頭文件：如 windows.h, pthread.h 放在 .c 中。
5. 面向用戶的註釋：用 Doxygen 風格描述函數契約、前置條件、錯誤碼。

多源文件共享一個接口頭文件

當一個邏輯模塊拆分為多個 .c 文件 (如 parser_lex.c, parser_yacc.c)：

• 共用一個 parser.h 對外暴露接口。
• 內部共享數據用單獨的 parser_internal.h (不對外發布)。
• 命名規範：<系統名>_<模塊名>.h。

說明性頭文件 (純宏/常量)

• 無對應 .c 文件。
• 命名：config.h, limits.h, error_codes.h。
• 內容：#define, enum, 類型別名。
• 不包含其他頭文件，不定義類型，不聲明函數/變量。

.c 文件編寫規範

1. 首行包含自帶頭文件：#include "module.h" (驗證 .h 自給自足)。
2. 內部函數/變量加 static 限制作用域。
3. 不使用 extern (那是 .h 的事)。
4. 確保內部標識符不與其他編譯單元衝突 (靜態鏈接單元)。
5. 實現 .h 中聲明的所有接口函數。

彙總：大型 C 專案目錄結構範例

project/
├── include/           # 公開接口頭文件
│   ├── core.h
│   ├── network.h
│   └── storage.h
├── src/               # 源文件 (不公開)
│   ├── core/
│   │   ├── core.h     # 內部接口
│   │   ├── core.c
│   │   └── utils.c
│   ├── network/
│   └── storage/
├── common/            # 共享說明性頭文件
│   ├── config.h
│   └── error_codes.h
├── Globel_Var.h/c     # 全局變量統一管理
└── main.c

遵循這套規範，配合靜態分析工具 (Cppcheck, Clang-Tidy) 和編譯器警告 (-Wmissing-prototypes -Wstrict-prototypes)，能構建出可維護、可擴展、可團隊協作的高質量 C 專案。