Skip to content

documentation.md

Latest commit

 

History

History
211 lines (155 loc) · 8.15 KB

documentation.md

File metadata and controls

211 lines (155 loc) · 8.15 KB
Raw

文档编写规范

目的

建立技术文档的编写标准，确保文档有用、可维护、与代码同步，避免"没有文档"或"文档过时比没文档更糟"的问题。

适用时机

  • 项目初始化时搭建文档结构
  • 完成功能后补充文档
  • 架构/接口发生变更时
  • 新成员加入需要上手指南
  • 文档审查（与代码审查同步）

流程步骤

第一部分：文档分类

类型 读者 内容 更新频率
README 所有人 项目简介、快速开始、技术栈 每次重大变更
架构文档 开发者 系统设计、模块关系、数据流 架构变更时
API 文档 前端/第三方 接口定义、参数、示例 接口变更时
操作手册 运维/部署者 部署步骤、配置说明、故障处理 部署流程变更时
决策记录 (ADR) 开发者 为什么这样设计 决策时
CHANGELOG 所有人 版本变更内容 每次发布
代码注释 开发者 复杂逻辑的 why 随代码更新

第二部分：README 标准

每个项目/模块的 README 必须包含：

# 项目名称

> 一句话描述项目做什么

## 快速开始

### 环境要求
- Node.js >= 18
- PostgreSQL >= 15

### 安装与运行
```bash
# 克隆、安装、配置、启动的命令

技术栈

  • 前端：...
  • 后端：...
  • 数据库：...

项目结构

（关键目录说明）

环境变量

（参见 .env.example）

开发指南

（如何运行测试、lint 等）

部署

（简述部署方式或链接到操作手册）


### 第三部分：代码注释规范

**何时写注释：**
- 解释 **为什么**（Why），不是做了什么（What）
- 复杂算法/业务逻辑
- 非显而易见的设计决策
- 临时方案/已知问题（TODO/FIXME/HACK）
- 公共 API 的参数和返回值

**何时不写：**
- 代码本身已经清晰的（好命名 > 注释）
- 注释掉的代码（直接删除，Git 有历史）
- 日志式注释（"2024-01-01 张三修改"）

**注释格式：**
```typescript
// 单行注释：解释紧接着的下一行代码

/**
 * 函数/类的文档注释
 * @param email - 用户邮箱
 * @returns 是否发送成功
 * @throws {ValidationError} 邮箱格式不正确时
 */

// TODO: [描述] — 待完成的功能
// FIXME: [描述] — 已知问题待修复
// HACK: [描述] — 临时方案，需要更好的解决

第四部分：文档维护节奏

文档即代码原则：

  • 文档和代码在同一个 PR 中更新
  • 代码审查时同时审查文档变更
  • CI 中可以检查文档是否过时（如链接检查）

维护触发点：

  • 新增功能 → 更新 README / API 文档
  • 架构变更 → 更新架构文档 + 写 ADR
  • 部署流程变更 → 更新操作手册
  • 发布版本 → 更新 CHANGELOG
  • 发现文档错误 → 立即修复

定期审查：

  • 每月检查一次文档准确性
  • 删除过时内容
  • 补充缺失内容

第四部分之补 · 历史文档的回写形态：「原文 + 就地加注」是唯一合法形态（常设；2026-09-13 批 7 落账）

背景：规格 / 版本记录 / 台账这类历史文档承载审计链 —— 它们的旧文本本身就是证据（「当时是怎么写的」决定了后来能不能对上账）。批 7 的文档回写统一采用 「原文一字不改 + 就地加注」：更正、作废、角色变更、状态回退一律以加注表达，旧句原样留档。

规则：

  • 🔴 唯一合法形态 = 「原文 + 就地加注」。不得字面删除 / 改写历史句；更正以「🔻 …（原文保留）」块表达，使原文可读、结论唯一。
  • 🔴 机器判据 = 「diff 只有 + 行、− 列为 0」（git diff --numstat 的删除列 + git diff 的 ^- 行数）。⇒ 派单里凡出现「删掉 / 移除 / 改成」这类字面删改措辞，一律按「加注作废 / 加注更正」执行，并在报告里指出该措辞与「− 列为 0」的冲突。不要为迁就措辞去破该判据。
  • 🔴 「不改历史原文」不能只看 numstat 删除列 —— 回写类单元必须另做「标题 / 锚逐条对拍」（HEAD 的 ^#{1,4}\s 行 vs 工作树逐条比对）。批 7 已发生一次首版误删小节标题、靠标题对拍自捉的事故（numstat 当时读作 +150/−0，掩盖了那次删除）。
  • 数字与结论必须带时点与来源：同一指标在不同时点的两个读数都留（例：「上游时点 578 文件 / 295–299 = 20」→「重跑时点 579 / 21」），并给出差额归因；不得只留一个使历史不可复算。
  • 引述纪律：入库文档里凡转述他人给的数字 / 路径，必须标明来源；若事后证伪，保留错文 + 就地加注更正，并登记「错文曾被入库」这一事实（本批已发生一次：控制方的引述错误被逐字抄进入库文档）。

第五部分：CHANGELOG 规范

遵循 Keep a Changelog 格式：

# Changelog

## [1.2.0] - 2024-03-15

### Added
- 用户头像上传功能
- 订单导出为 CSV

### Changed
- 优化列表页加载速度（减少 40% 请求）

### Fixed
- 修复并发下订单号重复问题

### Security
- 升级 jsonwebtoken 修复 CVE-2024-xxxx

第六部分：文档质量检查

好的文档应该：

  • 准确 — 与实际代码/行为一致
  • 完整 — 覆盖读者需要的所有信息
  • 简洁 — 不废话，直达要点
  • 可操作 — 读者能按步骤执行
  • 有示例 — 代码示例胜过千言万语
  • 有结构 — 标题层级清晰，可快速定位

第七部分：文档归档

归档定义：已实施完成、不再活跃维护的文档，移入 docs/archive/YYYY-MM-DD/ 快照（git mv 保留文件历史）。

判定标准：可归档 = 已落地实施的方案/设计文档、已验收的实施文档、已验证的知识卡（索引标 [ ] 已归档）、被取代的 ADR、已发布版本的规划文档、已执行的 spec/plan；不归档 = standards/、templates/、knowledge/index.md、生效 ADR、CHANGELOG、README、versions/ 内容。

流程（日收工，< 15 分钟）：① 整理昨日归档 tech-debt.md（已偿标 closed，未偿继承 carried）② 扫描今日提交登记新债务 ③ git mv 已实施文档入今日归档夹 ④ 写当日 README 索引 ⑤ 更新活跃区索引（链接改指归档路径 + 标 [ ] 已归档）⑥ 原子提交。

只读约束：技术债只认最新归档的 tech-debt.md；除最新一日外归档文件禁止修改。

详见 归档机制说明。

检查清单

  • README 包含快速开始指南
  • 环境变量有 .env.example 说明
  • 公共 API 有文档注释
  • 复杂逻辑有 why 注释
  • 无注释掉的代码残留
  • CHANGELOG 随版本更新
  • 架构变更有对应文档更新
  • 文档中的代码示例可运行
  • 无过时的链接/截图
  • 文档与代码在同一 PR 中更新

输出物

输出物 格式 存放位置
README Markdown 项目/模块根目录
架构文档 Markdown + 图 按需创建 docs/architecture/（或并入 Foresight/）
API 文档 OpenAPI / Markdown 按需创建 docs/api/（或并入对应服务文档）
CHANGELOG Markdown 项目根目录
操作手册 Markdown 按需创建 docs/operations/（或并入 server-ops 规范）

常见误区

误区 正确做法
写完代码不写文档 文档是交付物的一部分
注释解释"做了什么" 注释解释"为什么这样做"
文档写完就不管了 代码变文档也要变
注释掉代码留着 删掉，Git 有历史
文档全是文字无示例 代码示例 > 纯文字描述
一开始就写完美文档 先写最小可用，迭代完善

相关文档