====== C++ 头文件详解 (Header Files) ======

在 C++ 编程中，头文件（通常以 //.h// 或 //.hpp// 结尾）起着至关重要的作用。它们主要用于实现**声明与定义的分离**，支持模块化开发。

===== 1. 头文件的作用 =====

头文件主要承担以下职责：

  * **接口声明 (Interface Declaration)**: 向编译器展示函数、类的存在，但不包含具体实现（Templates 除外）。
  * **类型定义 (Type Definitions)**: 定义 Class, Struct, Enum, Union 等类型结构。
  * **模板定义 (Templates)**: 由于编译机制特殊，模板的声明和实现通常都放在头文件中。
  * **代码重用**: 通过 ``#include`` 指令，多个源文件可以共享同一个接口。

===== 2. 标准格式与结构 =====

一个规范的头文件必须包含**头文件保护符 (Header Guards)**，以防止被重复包含导致的编译错误。

==== 2.1 头文件保护 ====

有两种常见写法：

**写法 A：传统的宏定义保护 (标准写法)**
<code cpp>
#ifndef MY_MODULE_H
#define MY_MODULE_H

// ... 代码内容 ...

#endif // MY_MODULE_H
</code>

**写法 B：编译器指令 (现代写法)**
<code cpp>
#pragma once

// ... 代码内容 ...
</code>
//注：``#pragma once`` 更简洁，虽然不是标准 C++，但目前几乎所有主流编译器都支持。//

===== 3. 完整代码示例 =====

假设我们要编写一个简单的数学工具模块。

==== MathUtils.h (头文件) ====
<code cpp>
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

#include <vector> // 引入必要的标准库

namespace MyLib {

    // 1. 常量声明 (使用 extern)
    extern const double PI;

    // 2. 类声明
    class MathUtils {
    public:
        MathUtils();
        int add(int a, int b);
        static double calculateAverage(const std::vector<int>& numbers);
    private:
        int internalValue;
    };

    // 3. 模板函数 (必须在头文件中实现)
    template <typename T>
    T max(T a, T b) {
        return (a > b) ? a : b;
    }

}

#endif // MATH_UTILS_H
</code>

==== MathUtils.cpp (源文件) ====
<code cpp>
#include "MathUtils.h"
#include <numeric>

namespace MyLib {

    // 1. 变量定义
    const double PI = 3.1415926;

    // 2. 类成员函数实现
    MathUtils::MathUtils() : internalValue(0) {}

    int MathUtils::add(int a, int b) {
        return a + b;
    }

    double MathUtils::calculateAverage(const std::vector<int>& numbers) {
        if(numbers.empty()) return 0.0;
        double sum = std::accumulate(numbers.begin(), numbers.end(), 0.0);
        return sum / numbers.size();
    }
}
</code>

==== main.cpp (调用方) ====
<code cpp>
#include <iostream>
#include "MathUtils.h"

int main() {
    MyLib::MathUtils utils;
    std::cout << "1 + 2 = " << utils.add(1, 2) << std::endl;
    std::cout << "Max value: " << MyLib::max(10, 20) << std::endl;
    return 0;
}
</code>

===== 4. 最佳实践与禁忌 =====

在使用头文件时，请遵循以下原则：

  - **禁止在头文件中定义非内联函数或变量**:
    * 错误: ``int count = 0;`` (会导致 "Multiple Definition" 链接错误)
    * 正确: ``extern int count;`` (声明)
  - **禁止在头文件全局作用域使用 `using namespace`**:
    * 错误: ``using namespace std;`` (会污染所有包含此文件的源文件的命名空间)
    * 正确: 使用全名，如 ``std::vector``, ``std::string``。
  - **使用前置声明 (Forward Declaration)**:
    * 如果只需要类的指针或引用，尽量使用 ``class MyClass;`` 而不是 ``#include "MyClass.h"``，以减少编译依赖。