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 环境。

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

预期输出:

text
c-demo/CMakeLists.txt
c-demo/include/calculator.h
c-demo/src/calculator.c
c-demo/tests/test_calculator.c

build 没有出现在输出中,是因为最后一条命令只列出文件,而空目录本身不是文件。真正执行构建后,编译器和 CMake 生成的内容会进入 build,源码目录仍保持干净。

把公共接口和实现分开

假设 calculator.c 实现加法函数,而其他模块需要调用它,那么函数声明适合放在 include/calculator.h,实现放在 src/calculator.c。这样调用者只依赖公共接口,不需要知道实现文件内部还有哪些辅助函数。

相反,只被 calculator.c 使用的私有声明没有必要放进公共 include。公共头文件越少、越稳定,模块之间的耦合越容易控制。后续接入 CMake 时,也能更明确地区分“要编译的源文件”和“要暴露给其他目标的头文件搜索路径”。

不要把生成产物提交进源码区

build 的重要特性是可丢弃。对象文件、链接后的可执行文件、CMake 缓存以及测试生成物都不应该成为源码目录的一部分。常见做法是在版本控制中忽略它:

text
build/

这是配置片段,通常加入项目根目录的 .gitignore。验证方法是执行一次构建后检查 src、include 和 tests:这些目录中不应出现 .o、可执行文件或 CMake 缓存文件。

清晰目录结构的价值在于让后续工具有稳定边界:编译系统知道从哪里取源码,其他模块知道从哪里找公共接口,测试代码有独立入口,而所有可再生成的构建产物集中在一个可清理目录中。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计清晰的项目目录结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通