C/C++ 專案檔案結構規範：標頭檔與實作檔的最佳實踐

第 1 章 檔案結構

C/C++ 專案通常將程式碼分為兩類檔案：

• 標頭檔：副檔名 .h，存放宣告（declaration）。
• 實作檔：C 用 .c，C++ 慣用 .cpp（或 .cc、.cxx），存放定義/實作（definition/implementation）。

1.1 版權與版本聲明

置於標頭檔與實作檔開頭，包含：

1. 版權資訊
2. 檔案名稱、標識符、摘要
3. 目前版本號、作者/修改者、完成日期
4. 版本歷史資訊

/*
 * Copyright (c) 2001, 某公司
 * All rights reserved.
 *
 * 檔案名稱：filename.h
 * 摘 要：簡要描述本檔案內容
 *
 * 目前版本：1.1
 * 作 者：張三
 * 完成日期：2001年7月20日
 *
 * 取代版本：1.0
 * 原作者：李四
 * 完成日期：2001年5月10日
 */

1.2 標頭檔結構

標頭檔由三部分組成：

1. 版權與版本聲明
2. 前置處理區塊
3. 函式與類別結構宣告

關鍵規則

• 規則 1-2-1：使用 #ifndef/#define/#endif 防止重複引入。
• 規則 1-2-2：引用標準庫標頭檔用 #include <filename.h>。
• 規則 1-2-3：引用非標準庫標頭檔用 #include "filename.h"。
• 建議 1-2-1：標頭檔僅存放宣告，不存放定義。雖然 C++ 允許類別成員函式在宣告時定義（隱含 inline），但會造成風格不一致，弊大於利。建議將定義與宣告分離。
• 建議 1-2-2：不提倡全域變數，盡量避免標頭檔出現 extern int value 等宣告。

標頭檔範例

// 版權聲明省略
#ifndef GRAPHICS_H
#define GRAPHICS_H

#include <math.h>           // 標準庫
#include "myheader.h"       // 非標準庫

void Function1(...);        // 全域函式宣告

class Box {                 // 類別結構宣告
    ...
};

#endif

1.3 實作檔結構

1. 版權與版本聲明
2. 引入相關標頭檔
3. 程式實作本體（資料與程式碼）

// 版權聲明省略
#include "graphics.h"       // 引入對應標頭檔

// 全域函式實作
void Function1(...) { ... }

// 類別成員函式實作
void Box::Draw(...) { ... }

1.4 標頭檔的作用

1. 介面契約：提供介面宣告供呼叫端使用，隱藏實作細節（僅提供標頭檔與二進位庫即可）。
2. 型別安全檢查：編譯器比對實作與宣告是否一致，不一致即報錯，大幅減輕除錯負擔。

1.5 目錄結構建議

標頭檔超過 10 個時，建議分目錄管理：

• include/：公開標頭檔
• source/：實作檔（可多層目錄）
• 私有標頭檔（不對外公開）可與實作檔放同一目錄，強化資訊隱藏。