头文件中禁止非内联函数实现，须用inline或Static inline；防护宏按路径命名，#include顺序为当前→系统→第三方→项目；按逻辑边界拆分头文件，避免万能头；对外接口慎用std::String，优先const char*或string_view。
头文件里别写函数实现
绝大多数编译错误和链接重复定义（multiple definition of 'xxx'）都源于在头文件中直接写了非内联函数体。c++ 的 One Definition Rule（ODR）要求每个函数/变量在最终链接时只能有一个定义，而头文件被多个 .cpp 包含后，就等于把同一份实现复制进了多个编译单元。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 只在头文件中声明函数（
void foo();），实现在对应的.cpp文件里 - 确需在头文件中定义的，必须加
inline（如inline int add(int a, int b) { return a + b; }）或限定为static inline - 模板函数、constexpr 函数、类内定义的短成员函数可例外——它们天然满足 ODR 要求
#include 顺序和防护宏怎么写才不翻车
头文件包含顺序混乱会掩盖依赖问题；防护宏写错（比如拼错、没覆盖全部内容）会导致宏未生效，进而引发重定义或符号冲突。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 防护宏用
#ifndef XXX_H_+#define XXX_H_+#endif，宏名按路径转大写下划线（如UTILS_STRING_UTILS_H_），避免用__开头（保留给编译器） -
#include顺序：当前头文件 → 系统头文件（<vector></vector>）→ 第三方库 → 项目内其他头文件。这样能尽早暴露本头文件是否自洽（即不依赖其他头文件也能通过预处理） - 禁用
#pragma once—— 它不是标准 C++，部分嵌入式或老版本编译器不支持，且在硬链接/符号链接场景下可能失效
什么时候该拆头文件，什么时候该合并
头文件不是越细越好，也不是越少越好。拆得太碎，#include 链过长，编译时间飙升；合得太狠，一个头文件拖进整个模块依赖，改一行要全量重编。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 按逻辑接口边界拆：一个类、一组强相关的自由函数、一个配置结构体，各自一个头文件（如
config.h、logger.h） - 避免“万能头”（如
all.h或common.h）——它会让所有依赖它的源文件被迫重编译，哪怕只改了一个小工具函数 - 对稳定、极少改动的底层类型（如
using Status = int;、constexpr size_t kMaxSize = 1024;），可收进types.h这类轻量头，但禁止塞任何有实现或依赖外部头的内容
std::string 和 char* 混用时头文件怎么导出安全接口
对外暴露 std::string 参数或返回值，意味着调用方必须和你用完全一致的 STL 版本、编译器、运行时（尤其是 DLL 场景下极易崩溃）。很多团队踩过这个坑，最后回退到 C 风格接口。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 公开头文件中，输入参数优先用
const char*或std::string_view（C++17 起）；返回值避免直接返回std::string，改用输出参数（void get_name(char* buf, size_t len)）或返回const char*（指向内部静态缓冲区，需文档注明生命周期） - 如果必须用
std::string，确保整个工程统一构建配置（相同 ABI、相同 STL 实现），并在头文件顶部加注释：// Requires same stdlib as build environment - 第三方库头文件（如
json.hpp）不要直接暴露给用户代码——用 pimpl 或 wrapper 封装掉，否则你的头文件会变成别人的 STL 兼容性放大器
最常被忽略的是头文件的“隐式依赖”：你以为只改了 foo.h 里的注释，结果因为里面 #include "bar.h" 而导致所有包含它的源文件全部重编。真正的规范不是格式漂亮，是让每次修改的影响范围可预期、可控制。