命名空间、头文件与 ODR

用命名空间组织代码，理解头文件/源文件分离、单一定义规则、头文件保护、前向声明和 ADL。

大规模组织 C++ 代码

当 C++ 程序超出单个文件时，你需要机制来组织代码、防止名称冲突和管理文件间的依赖关系。C++ 提供了三个关键工具：

1. 命名空间将相关声明分组在一个名称下，防止不同库中同名实体之间的冲突。
2. 头文件和源文件将声明（有什么）与定义（如何工作）分离，实现分离编译。
3. 单一定义规则（ODR）是管理整个程序中每个实体可以被定义多少次的基本法则。

理解这些机制对于在任何真实世界的 C++ 项目中工作都是必不可少的。

命名空间

命名空间创建命名作用域以防止名称冲突。它们可以嵌套并在文件间重新打开：

namespaces.cpp

#include <iostream>

// Defining a namespace
namespace math {
    double pi = 3.14159265358979323846;

    double area_of_circle(double radius) {
        return pi * radius * radius;
    }

    // Nested namespace (C++17 shorthand)
    namespace geometry {
        struct Point { double x, y; };
    }
}

// C++17 nested namespace shorthand — equivalent to above
namespace math::geometry {
    double distance(Point a, Point b) {
        double dx = a.x - b.x;
        double dy = a.y - b.y;
        return std::sqrt(dx * dx + dy * dy);
    }
}

// Anonymous namespace — internal linkage (visible only in this file)
namespace {
    int internal_counter = 0;      // Like 'static' at file scope, but works for types too
}

int main() {
    // Fully qualified name
    std::cout << math::pi << '\n';

    // using declaration — imports one name
    using math::area_of_circle;
    std::cout << area_of_circle(5.0) << '\n';

    // using directive — imports ALL names (avoid in headers!)
    using namespace math::geometry;
    Point p1{0, 0}, p2{3, 4};

    // NEVER put 'using namespace std;' in a header file
    // It pollutes the global namespace for every file that includes the header
}

参数依赖查找（ADL）

参数依赖查找（ADL），也称为 Koenig 查找，是一条将名称查找扩展到函数参数所在命名空间的规则。当你调用函数时没有用命名空间限定，编译器也会搜索与参数类型关联的命名空间。

这就是为什么 std::cout << "hello" 能工作：<< 运算符定义在 std 命名空间中，而 cout 的类型是 std::ostream（在 std 中），所以 ADL 找到了正确的运算符。

ADL 也是为什么在泛型代码中应该写 swap(a, b) 而不加 std:: 限定 ── 它允许在类型命名空间中用户定义的 swap 函数被找到。模式是：using std::swap; swap(a, b); ── 这使 std::swap 成为后备，同时允许 ADL 找到更好的匹配。

ADL 可能在它引入你未预期的函数时带来意外。这是避免 using namespace std; 的另一个原因 ── 它可能与 ADL 产生歧义。

单一定义规则（ODR）

单一定义规则是 C++ 中最重要的规则之一。它有两部分：

1. 在一个翻译单元内，每个实体（变量、函数、类、枚举、模板）最多只能有一个定义。
2. 在整个程序中，每个非 inline 函数和非 inline 变量必须恰好有一个定义（在恰好一个 .cpp 文件中）。Inline 函数、inline 变量、类定义和模板可以在多个翻译单元中定义，但所有定义必须完全相同（逐 token 相同）。

违反 ODR 是未定义行为 ── 而且链接器可能不会捕获它。常见的违规包括：在头文件中定义非 inline 函数（每个包含它的 .cpp 文件都会产生一个定义），或在不同文件中有同一个类的不一致定义。

inline 是 ODR 合规的关键工具。它告诉链接器多个定义是可接受的（只要它们是相同的）。这就是为什么在类体内定义的函数隐式是 inline 的，以及为什么自 C++17 起命名空间作用域的 constexpr 变量隐式是 inline 的。

头文件 vs 源文件

头文件/源文件的约定在保持 ODR 合规的同时实现分离编译：

math_utils.hpp

// === math_utils.hpp ===
#pragma once                          // Include guard (non-standard but universal)
// Alternative: #ifndef MATH_UTILS_HPP / #define MATH_UTILS_HPP / ... / #endif

#include <cmath>
#include <cstdint>

namespace math_utils {

// Declarations — OK in headers (not definitions of non-inline entities)
double hypotenuse(double a, double b);          // Function declaration
extern int precision;                            // Variable declaration (extern!)

// Definitions OK in headers — templates and inline
template <typename T>
T clamp(T value, T low, T high) {               // Template: implicitly inline
    return (value < low) ? low : (value > high) ? high : value;
}

inline double degrees_to_radians(double deg) {   // Inline: ODR-safe in header
    return deg * 3.14159265358979323846 / 180.0;
}

constexpr std::int32_t max_iterations = 1000;    // constexpr: implicitly inline (C++17)

// Class definition — OK in headers (must be identical in all TUs)
struct Vec2 {
    double x, y;
    double length() const { return std::sqrt(x * x + y * y); }  // Implicitly inline
};

}  // namespace math_utils


// === math_utils.cpp ===
// #include "math_utils.hpp"
//
// namespace math_utils {
//
// // Definitions — exactly ONE .cpp file provides these
// double hypotenuse(double a, double b) {
//     return std::sqrt(a * a + b * b);
// }
//
// int precision = 6;   // Definition of the extern variable
//
// }  // namespace math_utils

最佳实践

前向声明告诉编译器一个名称存在而不提供其完整定义。对于类，class Foo; 让你可以使用 Foo* 和 Foo& 而不需要包含 Foo 的头文件。只有在访问成员、继承类或创建实例时才需要完整定义。

在头文件中最小化 #include 对大型项目至关重要：
- 头文件中只 #include 它自身需要的 ── 尽可能使用前向声明。
- 只有实现需要的 include 放在 .cpp 文件中，而不是头文件中。
- 每个头文件应该是自包含的：单独包含它必须能编译通过。
- .cpp 文件应该首先包含自己的头文件 ── 这验证了头文件是自包含的。