From 44bbea1b11711e7af436e2b6ed9cd7df2de119e8 Mon Sep 17 00:00:00 2001
From: Microindole <microindole@gmail.com>
Date: Fri, 8 May 2026 21:41:59 +0800
Subject: [PATCH] style: document include and file organization conventions

---
 AGENTS.md                     | 5 +++++
 arch/x86/boot/elf_loader.c    | 2 +-
 arch/x86/boot/elf_loader.h    | 2 +-
 arch/x86/boot/main.c          | 3 ++-
 arch/x86/boot/memory_map.h    | 3 ++-
 arch/x86/kernel/early_log.c   | 3 +--
 include/tianole/kernel_init.h | 2 +-
 kernel/boot_report.c          | 6 +++---
 kernel/early_log.c            | 4 ++--
 kernel/main.c                 | 4 ++--
 10 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0a65a3a..162c5c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,11 @@
 - 内部 C API 不加 `tianole_` 前缀；这是单一内核代码库，不把项目名重复进函数名和类型名。
 - 避免 `temp` / `tmp` 这类临时语义进入函数名、类型名和长期变量名；一次性局部变量可以用具体含义命名。
 - C 代码风格参考 Linux：tabs 缩进，函数左花括号另起一行，`if/for/while` 左花括号留在行尾。
+- 公共头文件使用 `<...>` include，例如 `<tianole/boot_info.h>`；同目录私有头文件使用 `"..."` include，例如 `"file.h"`。
+- 不使用 `../foo.h` 这类相对 include；如果一个头需要跨目录使用，应先确认它是否应该成为公共接口。
+- 长文件不是问题，职责混乱才是问题；一个文件可以较长，但必须代表一个清晰子系统、算法或驱动边界。
+- 不为了降低行数拆出 `utils.c`、`helpers.c` 这类无边界文件；按职责、生命周期和调用边界拆分。
+- 注释优先解释硬件约束、ABI 决策、内存所有权、并发语义和不明显的不变量；避免重复描述简单代码正在做什么。
 - 文本文件使用 LF 行尾。
 - `.clang-format` 是当前格式化约定；如果环境有 `clang-format`，新增或大改 C/H 文件后应按它格式化。
 - 根 `Makefile` 只做总控和通用规则；架构配置放在 `arch/<arch>/Makefile`，目录自己的源文件列表放在对应目录的 `Makefile` 中。
diff --git a/arch/x86/boot/elf_loader.c b/arch/x86/boot/elf_loader.c
index ef59419..f363036 100644
--- a/arch/x86/boot/elf_loader.c
+++ b/arch/x86/boot/elf_loader.c
@@ -1,6 +1,6 @@
 #include "elf_loader.h"
 
-#include "tianole/elf.h"
+#include <tianole/elf.h>
 
 static void *mem_copy(void *dst, const void *src, uint64_t size)
 {
diff --git a/arch/x86/boot/elf_loader.h b/arch/x86/boot/elf_loader.h
index f0a7054..f36d430 100644
--- a/arch/x86/boot/elf_loader.h
+++ b/arch/x86/boot/elf_loader.h
@@ -2,9 +2,9 @@
 #define X86_BOOT_ELF_LOADER_H
 
 #include <stdint.h>
+#include <tianole/boot_info.h>
 
 #include "efi.h"
-#include "tianole/boot_info.h"
 
 typedef void
 	__attribute__((sysv_abi)) (*kernel_entry_fn_t)(const boot_info_t *);
diff --git a/arch/x86/boot/main.c b/arch/x86/boot/main.c
index cf1cece..5c69f6d 100644
--- a/arch/x86/boot/main.c
+++ b/arch/x86/boot/main.c
@@ -1,9 +1,10 @@
+#include <tianole/boot_info.h>
+
 #include "debug_log.h"
 #include "efi.h"
 #include "elf_loader.h"
 #include "file.h"
 #include "memory_map.h"
-#include "tianole/boot_info.h"
 
 static efi_char16_t boot_banner_text[] = u"Tianole x86 bootloader.\r\n";
 static efi_char16_t kernel_path_text[] = u"\\kernel.elf";
diff --git a/arch/x86/boot/memory_map.h b/arch/x86/boot/memory_map.h
index f6d79dd..4d22bb6 100644
--- a/arch/x86/boot/memory_map.h
+++ b/arch/x86/boot/memory_map.h
@@ -1,8 +1,9 @@
 #ifndef X86_BOOT_MEMORY_MAP_H
 #define X86_BOOT_MEMORY_MAP_H
 
+#include <tianole/boot_info.h>
+
 #include "efi.h"
-#include "tianole/boot_info.h"
 
 efi_status boot_exit_services_with_latest_memory_map(efi_handle image_handle,
 	efi_system_table_t *system_table,
diff --git a/arch/x86/kernel/early_log.c b/arch/x86/kernel/early_log.c
index 12d92fa..a86edc3 100644
--- a/arch/x86/kernel/early_log.c
+++ b/arch/x86/kernel/early_log.c
@@ -1,6 +1,5 @@
 #include <stdint.h>
-
-#include "tianole/arch.h"
+#include <tianole/arch.h>
 
 #define X86_QEMU_DEBUG_PORT 0xe9
 
diff --git a/include/tianole/kernel_init.h b/include/tianole/kernel_init.h
index 9e137dd..a6326b5 100644
--- a/include/tianole/kernel_init.h
+++ b/include/tianole/kernel_init.h
@@ -1,7 +1,7 @@
 #ifndef KERNEL_INIT_H
 #define KERNEL_INIT_H
 
-#include "tianole/boot_info.h"
+#include <tianole/boot_info.h>
 
 void kernel_report_boot_state(const boot_info_t *boot_info);
 
diff --git a/kernel/boot_report.c b/kernel/boot_report.c
index 9ea68ff..6311e21 100644
--- a/kernel/boot_report.c
+++ b/kernel/boot_report.c
@@ -1,8 +1,8 @@
 #include <stdint.h>
 
-#include "tianole/boot_info.h"
-#include "tianole/early_log.h"
-#include "tianole/kernel_init.h"
+#include <tianole/boot_info.h>
+#include <tianole/early_log.h>
+#include <tianole/kernel_init.h>
 
 static void log_memory_map_summary(const boot_info_t *boot_info)
 {
diff --git a/kernel/early_log.c b/kernel/early_log.c
index 13d3c32..e354f9d 100644
--- a/kernel/early_log.c
+++ b/kernel/early_log.c
@@ -1,7 +1,7 @@
 #include <stdint.h>
 
-#include "tianole/arch.h"
-#include "tianole/early_log.h"
+#include <tianole/arch.h>
+#include <tianole/early_log.h>
 
 static int early_log_ready;
 
diff --git a/kernel/main.c b/kernel/main.c
index aeadaea..5046b25 100644
--- a/kernel/main.c
+++ b/kernel/main.c
@@ -1,5 +1,5 @@
-#include "tianole/early_log.h"
-#include "tianole/kernel_init.h"
+#include <tianole/early_log.h>
+#include <tianole/kernel_init.h>
 
 void kernel_main(const boot_info_t *boot_info)
 {