C / C++ / 系统课时
设计清晰的项目目录结构
设计清晰的项目目录结构
当 C 项目从一个 main.c 增长到多个源文件后,最容易出现的问题不是代码不会写,而是源码、头文件、测试和构建产物互相混放。本节用一套小而稳定的目录约定,把“写代码、对外暴露接口、运行测试、生成产物”四类职责分开。
学习目标
- 能说明
src、include、tests、build各自应该存放什么 - 能为一个多文件 C 项目建立可继续接入 CMake 和测试框架的目录骨架
- 能避免把生成文件、私有头文件和测试代码混入错误目录
先按职责分目录
一个适合中小型 C 项目的起点可以包含项目根目录、src、include、tests 和 build。根目录保存面向整个项目的文件,例如 CMakeLists.txt、README 和版本控制配置;其余目录只承担单一职责。
src:放实现文件和仅供实现内部使用的私有代码,例如calculator.c。include:放需要被其他模块包含的公共头文件,例如calculator.h。tests:放测试源码和测试辅助代码,不让测试入口混进正式程序。build:放编译系统生成的目标文件、可执行文件和缓存。它应当可以整体删除后重新生成。

这里的关键不是目录名字必须完全相同,而是稳定的职责边界。例如小项目把私有头文件留在 src 中没有问题;只有希望其他模块通过稳定接口访问的头文件,才有必要放进 include。
建立一个最小目录骨架
下面的命令创建一个可继续扩展的示例工程,并列出结果。它使用 Bash 的花括号展开语法,适用于常见 Linux、macOS 或 Git Bash 环境。
rm -rf c-demo
mkdir -p c-demo/{src,include,tests,build}
touch c-demo/CMakeLists.txt
touch c-demo/src/calculator.c
touch c-demo/include/calculator.h
touch c-demo/tests/test_calculator.c
find c-demo -maxdepth 2 -type f | sort预期输出:
c-demo/CMakeLists.txt
c-demo/include/calculator.h
c-demo/src/calculator.c
c-demo/tests/test_calculator.cbuild 没有出现在输出中,是因为最后一条命令只列出文件,而空目录本身不是文件。真正执行构建后,编译器和 CMake 生成的内容会进入 build,源码目录仍保持干净。
把公共接口和实现分开
假设 calculator.c 实现加法函数,而其他模块需要调用它,那么函数声明适合放在 include/calculator.h,实现放在 src/calculator.c。这样调用者只依赖公共接口,不需要知道实现文件内部还有哪些辅助函数。
相反,只被 calculator.c 使用的私有声明没有必要放进公共 include。公共头文件越少、越稳定,模块之间的耦合越容易控制。后续接入 CMake 时,也能更明确地区分“要编译的源文件”和“要暴露给其他目标的头文件搜索路径”。
不要把生成产物提交进源码区
build 的重要特性是可丢弃。对象文件、链接后的可执行文件、CMake 缓存以及测试生成物都不应该成为源码目录的一部分。常见做法是在版本控制中忽略它:
build/这是配置片段,通常加入项目根目录的 .gitignore。验证方法是执行一次构建后检查 src、include 和 tests:这些目录中不应出现 .o、可执行文件或 CMake 缓存文件。
清晰目录结构的价值在于让后续工具有稳定边界:编译系统知道从哪里取源码,其他模块知道从哪里找公共接口,测试代码有独立入口,而所有可再生成的构建产物集中在一个可清理目录中。