为自建代码目录补齐 README,建立目录级导航体系
- 新增 26 份目录 README:App/(+log,task,util,protocol)、Drivers/BSP/(+8子系统)、 Src/、Inc/、scripts/、tools/(+6子工具)、test/、MDK-ARM/、simulator/(+sim,tests) - 每份含:定位、文件清单表、关键约束/陷阱、指向 docs 权威文档 - 第三方库与生成代码目录排除(CMSIS/HAL/Middlewares/Lib/SDL2) - docs/文档规范.md 新增 §1.1b 代码目录 README 约定;根 README 目录结构加入说明
This commit is contained in:
@@ -16,6 +16,23 @@
|
||||
| **按领域归入子目录** | 顶层不放散落 `.md`;新领域先建无空格子目录,再在 [`README.md`](README.md) 登记 |
|
||||
| 现有目录 | `架构设计/` `子系统设计/` `网络/` `测试说明/` `代码规范/` `内存管理/` `问题记录/` `审查记录/` `环境与部署/` `UI设计/` `硬件平台/` `芯片手册/` `images/` |
|
||||
|
||||
### 1.1b 代码目录的 README.md
|
||||
|
||||
**每个自建代码目录**(非第三方库、非 HAL/CMSIS 生成)**必须有一份 `README.md`**,
|
||||
说明该目录的职责、文件清单与关键约束,让新接手者不必读遍代码即可建立认知。
|
||||
|
||||
| 规则 | 说明 |
|
||||
|---|---|
|
||||
| **覆盖范围** | `App/`(含 `log/` `task/` `util/`)、`Drivers/BSP/`(含各芯片子目录)、`Src/`、`Inc/`、`scripts/`、`tools/`(含各子工具)、`test/`、`MDK-ARM/`、`simulator/`(含 `sim/` `tests/`)、`docs/` |
|
||||
| **排除** | 第三方库与生成代码:`Drivers/CMSIS/`、`Drivers/STM32F4xx_HAL_Driver/`、`Middlewares/Third_Party/`、`Lib/`(FatFs/dhara/lvgl)、`simulator/SDL2/`、构建产物目录 |
|
||||
| **必备内容** | ① 一句话定位 + 是否自研 ② 文件/子目录清单表(每个一句话作用)③ 关键约束或陷阱(改前须知)④ 指向 `docs/` 权威文档的链接 |
|
||||
| **命名** | 一律 `README.md`(大写),放该目录根部 |
|
||||
| **链接** | 目录间互链用**同级相对路径**(如 `../NET/README.md`);指向 `docs/` 用**仓库根相对路径** |
|
||||
| **门禁** | README 内所有链接受 `doc-links` 钩子检查;新增/改名目录或文件后须同步更新对应 README |
|
||||
|
||||
> 目的:**目录即文档的入口**。根 `README.md` 给全局地图,各目录 `README.md` 给局部细节,
|
||||
> 二者构成"地图 + 地标"的导航体系(避免所有信息堆在单一 README)。
|
||||
|
||||
### 1.2 文件名
|
||||
|
||||
| 规则 | 说明 |
|
||||
|
||||
Reference in New Issue
Block a user