# Code Style 这个文档记录 agent 修改 Tianole 代码时必须遵守的代码组织和风格规则。 ## 总原则 - 参考 Linux 的工程风格，但不机械照抄 Linux 的历史实现。 - 简化实现可以接受，写死架构边界、设备假设、内存布局和调用路径不接受。 - 文件按职责拆分，不按行数拆分。 - 入口文件只编排流程，不承载具体功能细节。 ## Include 风格 - 公共头文件使用 `<...>`，例如 ``。 - 同目录私有头文件使用 `"..."`，例如 `"file.h"`。 - 不使用 `../foo.h` 这类相对 include。 - 如果一个头文件需要跨目录使用，先判断它是否应该成为公共接口。 - `include/tianole/` 放尽量架构无关的共享接口。 - `arch//include/` 放架构公开接口。 ## 文件组织 - 长文件不是问题，职责混乱才是问题。 - 一个文件可以较长，但必须代表一个清晰子系统、算法或驱动边界。 - 不为了降低行数拆出 `utils.c`、`helpers.c` 这类无边界文件。 - 按职责、生命周期、所有权和调用边界拆分。 - `kernel/main.c`、`boot/main.c` 这类入口文件应保持短，只串联阶段。 - `mm/` 是顶层内存管理子系统目录，不放在 `kernel/mm/` 下。 - 顶层目录参考 `docs/agents/linux-layout.md`；可以预留目录，但不要放临时代码。 ## 命名 - 内部 C API 不加 `tianole_` 前缀。 - 架构目录内部不要重复架构名前缀；例如 `arch/x86/kernel/` 内使用 `gdt_init()`，不要写成 `x86_gdt_init()`。 - 跨通用层暴露的架构入口使用 `arch_` 前缀，例如 `arch_traps_init()`。 - 描述硬件规格的文档文字可以写 `x86_64`，但代码文件名和内部符号不需要反复带 `x86`。 - 避免 `temp`、`tmp` 这类临时语义进入函数名、类型名和长期变量名。 - 一次性局部变量也应尽量使用具体含义命名。 - 名字应表达长期职责，不表达当前实现的临时状态。 ## 注释 - 注释优先解释硬件约束、ABI 决策、内存所有权、并发语义和不明显的不变量。 - 不写重复描述简单代码行为的注释。 - 如果代码依赖硬件手册、启动协议、调用顺序或特殊寄存器状态，应写明约束。 - 如果一个实现是临时简化，应写清楚后续替换边界，而不是写成永久接口。 ## C 格式 - 使用 `.clang-format` 作为当前格式化规则。 - 使用 tab 缩进。 - 函数左花括号另起一行。 - `if/for/while` 左花括号留在行尾。 - 文本文件使用 LF 行尾。 ## 构建文件 - 根 `Makefile` 只做总控和通用规则。 - 架构配置放在 `arch//Makefile`。 - 目录自己的源文件列表放在对应目录的 `Makefile`。 - 顶层子系统目录可以有自己的 `Makefile`，例如 `mm/Makefile`。 - 不新增独立 `mk/` 目录，除非后续有明确且无法避免的理由。 ## 脚本组织 - `scripts/check.sh` 是本地和 CI 共用的检查入口，只做编排。 - 可独立执行的检查放在 `scripts/checks/`。 - 多个检查共享的函数放在 `scripts/lib/`。 - 不把所有检查逻辑持续堆进 `scripts/check.sh`。 - 项目结构规则放在 `scripts/tools/check_structure.py`，由 `scripts/checks/structure.sh` 调用；优先用宿主 Linux/LLVM 工具实现底层检查，把 Tianole 自己的目录和 include 约束固化在轻量 Python 工具里。 - 启动阶段内核自测集中放在 `kernel/selftest/`，不要散落在具体实现目录里。 ## 验证 - 新增或大改 C/H 文件后运行 `clang-format`。 - 提交前至少运行 `scripts/check.sh`。 - 如果只是文档修改，至少运行 `git diff --check`。