高質量 C++/C 編程指南：第 1 章 文件結構規範

第 1 章 文件結構

在 C++/C 程序開發中，標準做法是將程式碼拆分為兩類文件：頭文件與定義文件。頭文件負責存放聲明，定義文件則包含具體實現。這種分離不僅符合模組化設計原則，也能有效控制編譯依賴關係。

1.1 文件命名慣例

• C++/C 通用頭文件：.h
• C 語言定義文件：.c
• C++ 定義文件：通常用 .cpp，部分系統採用 .cc 或 .cxx

1.2 版權與版本聲明

每個文件開頭必須包含標準化的版權與版本資訊，主要涵蓋：

1. 版權信息
2. 文件名稱、標識符、功能摘要
3. 當前版本號、作者/修改者、完成日期
4. 版本歷史記錄

/*
 * Copyright (c) 2001, 上海貝爾有限公司網絡應用事業部
 * All rights reserved.
 *
 * 文件名稱： filename.h
 * 文件標識： 見配置管理計劃書
 * 摘 要： 簡要描述本文件的內容
 *
 * 當前版本： 1.1
 * 作 者： 輸入作者（或修改者）名字
 * 完成日期： 2001年7月20日
 *
 * 取代版本 ： 1.0
 * 原作者 ： 輸入原作者（或修改者）名字
 * 完成日期： 2001年5月10日
 */

1.3 頭文件結構規範

合規的頭文件由三部分組成：

1. 版權與版本聲明
2. 預處理塊
3. 函數、類結構聲明

以 graphics.h 為例：

// 版權和版本聲明見示例 1-1，此處省略。

#ifndef GRAPHICS_H   // 防止 graphics.h 被重複引用
#define GRAPHICS_H

#include <math.h>       // 引用標準庫頭文件
...
#include "myheader.h"  // 引用非標準庫頭文件
...

void Function1(...);   // 全局函數聲明
...

class Box              // 類結構聲明
{
...
};

#endif

核心規則

• 規則 1-2-1：使用 #ifndef/#define/#endif 防止重複包含
• 規則 1-2-2：標準庫頭文件用 #include <filename.h>
• 規則 1-2-3：非標準庫頭文件用 #include "filename.h"

重要建議

• 建議 1-2-1：頭文件僅放聲明，不放定義。即使成員函數極小，也應將定義移至 .cpp 文件，避免隱式內聯導致風格不一致
• 建議 1-2-2：不提倡全局變量，盡量避免在頭文件出現 extern int value 這類聲明

1.4 定義文件結構

定義文件同樣包含三部分：

1. 版權與版本聲明
2. 所需頭文件引用（首行必須包含對應的 .h 文件）
3. 程序實現體（數據與代碼）

// 版權和版本聲明見示例 1-1，此處省略。

#include "graphics.h"  // 引用對應頭文件
...

// 全局函數實現
void Function1(...)
{
...
}

// 類成員函數實現
void Box::Draw(...)
{
...
}

1.5 頭文件的核心作用

1. 封裝庫功能：僅提供頭文件與二進制庫，隱藏實現細節，使用者按接口聲明調用
2. 強化類型安全：編譯器會在實現與聲明不一致時報錯，大幅降低調試成本

1.6 目錄組織建議

當頭文件超過 10 個時，建議採用分目錄管理：

• 公開頭文件 → include/ 目錄
• 定義文件 → source/ 目錄（可多級）
• 私有頭文件（僅內部使用） → 與定義文件同目錄，強化資訊隱藏