【C++】包含头文件顺序

原创于 2025-03-11 15:00:50 发布 · 1.2k 阅读

CC 4.0 BY-SA版权

文章标签：

在 C++ 中，头文件的包含顺序和路径规范对代码的可维护性、可移植性和编译正确性非常重要。你提到了一种推荐的做法，即项目内头文件应按照项目源代码目录树结构排列，并且避免使用相对路径符号 .（当前目录）和 ..（父目录）。这种做法在大型项目中尤其常见，比如 Google 的代码风格指南（Google C++ Style Guide）。下面我详细解释这种规则及其实现方式。

规则背景

在项目开发中，头文件的包含方式会影响：

可读性：清晰的路径结构让开发者更容易理解文件依赖关系。
可移植性：避免相对路径（如 ./ 或 ../）可以减少在不同构建系统或目录结构下的路径解析问题。
编译器行为：通过规范化路径，可以更好地利用编译器的 -I（include 路径）选项。

例如，对于一个项目 google-awesome-project，其目录结构可能是：

google-awesome-project/
├── src/
│   ├── base/
│   │   └── logging.h
│   └── foo/
│       └── bar.cc
└── include/

假设 bar.cc 需要包含 logging.h，按照你的描述，推荐的包含方式是基于项目源代码的目录树结构，而不是使用相对路径。

完整示例

假设项目结构如下：

google-awesome-project/
├── src/
│   ├── base/
│   │   └── logging.h
│   └── foo/
│       └── bar.cc

`logging.h` 文件

// google-awesome-project/src/base/logging.h
#ifndef BASE_LOGGING_H
#define BASE_LOGGING_H

void log(const char* message);

#endif

`bar.cc` 文件

// google-awesome-project/src/foo/bar.cc
#include "base/logging.h"  // 规范化路径

int main() {
    log("Hello, world!");
    return 0;
}

编译命令

g++ -I../src -o bar bar.cc ../src/base/logging.o

-I../src 告诉编译器将 src 目录加入 include 路径。
因此，#include "base/logging.h" 会被解析为 google-awesome-project/src/base/logging.h。

头文件包含顺序的更广建议

除了你提到的项目内头文件路径规范，C++ 项目中通常还有一个更完整的头文件包含顺序约定，以确保代码清晰并减少依赖问题：

对应的头文件（如果当前是实现文件 .cc 或 .cpp）：
- 例如，bar.cc 首先包含 bar.h。
C 系统头文件（如 <stdio.h>、<stdlib.h>）。
C++ 标准库头文件（如 <iostream>、<vector>）。
第三方库头文件（如 Boost、Qt）。
项目内头文件（按目录树结构，如 base/logging.h）。

示例

// google-awesome-project/src/foo/bar.cc
#include "foo/bar.h"         // 对应的头文件
#include <stdio.h>           // C 系统头文件
#include <iostream>         // C++ 标准库
#include "base/logging.h"    // 项目内头文件

int main() {
    log("Test");
    std::cout << "Hello" << std::endl;
    return 0;
}

Google Style Guide 的补充

你提到的 google-awesome-project/src/base/logging.h 示例与 Google C++ Style Guide 一致。Google 的规范还建议：

使用双引号 "" 而非尖括号 <> 来包含项目内的头文件。
头文件路径应尽量简洁，避免冗余前缀（如 src/google-awesome-project/base/logging.h 可能简化为 base/logging.h）。
依赖构建工具（如 Bazel）来管理 include 路径，而不是硬编码相对路径。