C语言头文件应放置哪些声明？项目头文件使用方式存疑

这是个非常典型的C项目组织问题，很多刚上手模块化开发的开发者都会踩类似的坑。咱们一步步理清楚头文件的核心逻辑和你的问题：

头文件的核心原则 #

头文件本质是模块对外暴露的接口契约——只放需要被其他.c文件复用、调用的内容，模块内部私有的实现细节，坚决留在对应的.c文件里。

应该放进头文件的内容 #

• 对外公开的函数声明：如果某个函数是模块提供给其他代码调用的API，必须放在头文件里。函数声明默认带extern属性，加不加都可以，但显式写上extern会让接口更清晰，比如：extern int calculate_sum(int a, int b);
• 跨模块使用的typedef/结构体/枚举：如果其他模块需要用这个类型来定义变量、作为函数参数或返回值，就必须放进头文件。比如你写了一个日志模块，typedef enum LogLevel LogLevel;肯定要放头文件，这样其他文件才能用LogLevel类型来指定日志级别。
• 全局共享的宏定义：多个模块都需要用到的常量、宏函数，比如#define MAX_CONNECTION 64或者#define MIN(a,b) ((a)<(b)?(a):(b))，适合放在头文件里。
• 跨文件访问的全局变量声明：如果有需要被其他模块读取/修改的全局变量，在头文件里用extern声明（比如extern int global_runtime_flag;），而变量的定义（赋值）必须放在对应的.c文件里。

绝对不能放进头文件的内容 #

• 仅当前.c文件使用的typedef/结构体：比如你在某个.c文件里定义了一个只用来辅助内部逻辑的struct TempCache，完全不需要其他文件知道，那就直接放在.c文件的顶部，别放进头文件。这样既能减少头文件冗余，还能实现信息隐藏，避免其他模块不小心依赖内部细节。
• 静态函数（static修饰）的声明：被static修饰的函数只能在当前.c文件内调用，根本不需要对外暴露，直接在.c文件里声明（比如放在函数实现上方，或者文件顶部的声明区）即可。
• 函数的实现代码：绝对不要把函数体写进头文件，除非是inline函数（还要处理好重复定义的问题）。否则多个.c文件包含这个头文件时，会触发重复定义的编译错误。
• 全局变量的定义：比如int global_runtime_flag = 0;这种带赋值的定义不能放头文件，否则每个包含头文件的.c文件都会生成一个变量副本，链接时会报错。

对你当前做法的调整建议 #

你现在把所有typedef和函数声明都放头文件的做法确实不太妥当：

• 那些仅单个.c文件使用的typedef，放进头文件会让头文件臃肿，还会暴露内部细节——万一以后你修改这个typedef的结构，会导致所有包含该头文件的文件都要重新编译，增加不必要的编译依赖。
• 那些不会被其他源文件调用的函数（也就是静态函数），它们的声明完全没必要出现在头文件里，留在.c文件内部即可。

另外，记得给所有头文件加上保护宏（或者用#pragma once），防止重复包含导致的编译错误：

#ifndef MODULE_NAME_H
#define MODULE_NAME_H

// 头文件的所有内容都放在这里

#endif // MODULE_NAME_H

内容的提问来源于stack exchange，提问作者apadana