高质量头文件需满足不拖累编译、不暴露实现、不引发冲突；必须用#ifndef或#pragma once保护；只放声明不放定义；优先前向声明；接口设计克制，避免泄露实现细节。
高质量的头文件不是“写得全”，而是“不拖累编译、不暴露实现、不引发冲突”。它直接影响整个项目的构建速度、链接稳定性与接口清晰度。
头文件必须带保护，且命名要唯一
没有 #ifndef/#define/#endif 或 #pragma once 的头文件，在多处被包含时会直接触发 redefinition 错误——比如类重复声明、函数重复声明。这不是警告，是硬性编译失败。
-
#ifndef方式更稳妥：宏名建议用项目前缀 + 路径 + 文件名 +_H_，例如MYAPP_UTILS_MATH_H_，避免和第三方库撞名 -
#pragma once更简洁，但某些老旧构建环境（如部分嵌入式交叉编译器）可能不支持，团队若统一用 GCC/Clang/MSVC 则可放心启用 - 不要混用两种方式；也不要写成
#ifndef MYCLASS_H这种易冲突的短名——MYCLASS_H在大型项目中大概率重复
头文件里只放声明，别放定义
定义（比如变量初始化、函数体、静态成员变量）一旦出现在头文件中，被多个 .cpp 包含后，链接阶段就会报 multiple definition 错误。
- 函数声明可以，函数实现不行（除非加
inline或写在类内且满足内联条件） - 类声明可以，类外定义的成员函数必须挪到
.cpp中 -
const全局变量可以（C++17 起隐式inline），但int value = 42;不行；想导出变量，应在头文件中写extern int value;，并在某个.cpp中定义 - 模板和
constexpr函数例外：它们必须定义在头文件里，否则实例化失败
减少包含，优先用前向声明
每多一个 #include，就多一次头文件解析、宏展开和符号表构建——这直接拖慢编译。很多头文件变慢，根源就在无节制包含。
立即学习“C++免费学习笔记（深入）”；
- 如果只用到某个类型的指针或引用（如
class Logger*、const Shape&），就用前向声明class Logger;，而不是#include "Logger.h" - 只有真正需要知道大小、调用构造/析构、继承或访问成员时，才必须包含完整头文件
- 标准库头文件尽量用
#include <vector></vector>形式；项目内头文件一律用#include "path/to/file.h"，避免路径歧义 - 把
#include按依赖稳定度排序：先系统库，再第三方，最后项目内；同级头文件按字母序排列，便于排查循环依赖
接口设计要克制，别把实现细节漏出去
头文件是模块对外契约。一旦暴露了不该暴露的东西，后续重构就会束手束脚——改个私有成员名，可能触发全量重编译。
- 避免在头文件中
#include实现依赖的头文件（比如DatabaseImpl.h），改用 PIMPL 或抽象基类+工厂 - 不要在头文件中暴露
std::vector<detail></detail>这类具体容器类型，考虑用std::span<const detail></const>或自定义迭代器接口 - 类成员函数默认不内联；超过 5 行、含循环或
switch的函数，坚决不放在头文件中定义 - 所有非
public成员、辅助函数、内部枚举都应从头文件中剔除——它们属于.cpp的领地
最容易被忽略的一点：头文件的修改成本远高于源文件。哪怕只是加了一个 const 修饰符或改了个参数名，只要它出现在头文件中，所有依赖它的翻译单元都得重新编译。所以每次动头文件，都要问一句：这个改动真的必须暴露给用户吗？
