00.专栏写作模板 · 代码医院版

本文件用于规范《代码品质工坊 · 代码医院》全 14 篇的统一写作风格。 每写一篇新文章前，请先对照本模板检查骨架是否齐全。

与 C++ 专栏模板同源，但融入医院隐喻、三医生查房、病案编号三大专栏特色，形成"叙事 + 分层 + 检索"三合一。

---

一、命名与编号

• 命名格式：NN.标题.md，标题限定 8-9 个汉字（对应目录整齐）
• 编号 NN 为两位数，从 00（README/序篇）开始
• 标题要"科室 + 病症"或"手法 + 落点"结构，避免空泛
  • ❌ "代码审查" → ✅ "代码审查文化"
  • ❌ "单元测试" → ✅ "单元测试兜底"
• 二级、三级标题：最少 6 字，最多 9 字，对仗工整

---

二、十章骨架

每篇文章必须包含以下 10 章，缺一不可。其中第 5、6、7 章为"三医生查房"专栏特色：

1. 案例引入        ← 一份"急诊病例"：真实事故 / 反直觉代码，配主诉+检查数据
2. 病理诊断        ← 用 Clean Code 语言给这段代码"命名坏味道"，登记病案编号
3. 病因追溯        ← 从代码追到人 / 组织 / 流程，坏味道的深层来源
4. 治疗方案总纲     ← 一张总图 + "为什么选这套方案"的反向论证
5. 【住院医查房】   ← 初级视角（1-3 年）：命名/函数/格式层面的表面手术
6. 【主治查房】     ← 高级视角（3-8 年）：设计/职责/边界层面的中层手术
7. 【主任查房】     ← 架构师视角（8+ 年）：系统/组织/文化层面的深层手术
8. 术后康复曲线     ← 治疗前/后的度量对比：复杂度/覆盖率/事故数/工时
9. 病案归档        ← 本篇涉及的所有病案编号清单，形成可检索索引
10. 综合案例串讲    ← 回扣第 1 章的病例，逐条回答疑问 + 3~4 条设计哲学

核心原则：

1. 第 1 章埋的所有疑问，第 10 章必须全部回答。
2. 第 5-7 章"三医生查房"是本专栏的灵魂——同一段病灶，从三个视角各切一刀，读者可按身份自选深度。
3. 中间章节是"取证过程"与"手术记录"。

---

三、目录骨架

# NN.文章标题

#### 目录介绍

- [一、命名与编号](#一命名与编号)
- [二、十章骨架](#二十章骨架)
- [三、目录骨架](#三目录骨架)
- [四、写作风格红线](#四写作风格红线)
    - [4.1 语气与人称](#41-语气与人称)
    - [4.2 三医生分层](#42-三医生分层)
    - [4.3 三段式论证](#43-三段式论证)
    - [4.4 图示要求](#44-图示要求)
    - [4.5 代码片段](#45-代码片段)
- [五、病案编号系统](#五病案编号系统)
    - [5.1 编号约定](#51-编号约定)
    - [5.2 病案编号使用规范](#52-病案编号使用规范)
    - [5.3 病案卡片模板](#53-病案卡片模板)
- [六、末章三件套](#六末章三件套)
- [七、章节自检清单](#七章节自检清单)
- [八、章数与篇幅](#八章数与篇幅)
- [九、写作前置流程](#九写作前置流程)
- [十、贯穿角色档](#十贯穿角色档)
- [十一、贯穿病例档](#十一贯穿病例档)
- [十二、参考标杆](#十二参考标杆)
- [十三、专属专栏要求](#十三专属专栏要求)

---

## 四、写作风格红线

### 4.1 语气与人称

- 用 **"我们"** 不用 **"你/笔者"**——拉近距离，把读者当同行
- 医院隐喻要**用得克制**：不是每句话都要"病人""诊断"——避免油腻
- 关键结论用 `**加粗**`，给读者打靶子
- 句末避免"了哦呢嘛"等弱化语气词

### 4.2 三医生分层

三个视角**不是简单的深浅之差**，而是**关注面不同**：

| 视角 | 主要关注 | 举例（同一段吞异常的代码） |
|---|---|---|
| 🟢 住院医 | 单文件、几行代码内的可见问题 | "把 `catch(Exception e){}` 改成具体异常类型" |
| 🟡 主治 | 模块、类、接口层面的设计问题 | "错误处理策略要在接口契约里明示" |
| 🔴 主任 | 系统、团队、流程层面的根源问题 | "为什么团队会形成'先跑起来再说'的文化" |

**规则**：
1. 三视角**不能只是深浅递进**，必须有**独立的关注面**——避免"深浅版重复三遍"。
2. 每一视角**独立自洽**——只读住院医版的读者也能完整学到东西。
3. 每一视角**结尾必须给"带走清单"**（3-5 条可执行动作）。

### 4.3 三段式论证

每个核心原理点必须按 **"疑惑 → 论证 → 结论"** 三段式展开：

```markdown
**疑惑**：为什么"提炼函数"是重构 18 招里最先该学的？

**论证**：
1. 一个 500 行的函数没法测——测试需要"可命名的行为单元"
2. 提炼函数把"隐性行为"变成"命名的显性行为"，是所有其它重构的前提
3. Fowler《重构》第 2 版把它列为第 1 号手法（编号 6.1），不是偶然
4. 反向验证：《修改代码的艺术》Feathers 遇到遗留代码时，第一步永远是"找到接缝并提取"
5. 数据佐证：在我们订单案例里，提炼函数一步就把圈复杂度 68 降到 22

**结论**：提炼函数不是"重构的一招"，是"让所有其它重构成为可能"的底层动作——先学它，才能安全动别的。

严禁直接抛结论——读者要的是推导过程。

4.4 图示要求

• 决策/流程用 mermaid 流程图
• 代码演进用 before/after 对照表
• 度量变化用表格 + 曲线描述
• 类关系/职责边界用 ASCII 图（用 Unicode 框线 ┌─┐│└─┘）
• 每个核心子章节至少有 1 个图或表

4.5 代码片段

• 主线用 Java（承接订单系统案例），关键手法给 Go / Python / TypeScript 对照
• 单段代码 不超过 60 行，超过就拆
• 每段 before 代码必须配 after 代码
• 注释用中文，贴在被解释行的右侧或上方
• 反面案例明确标注 // ⚠️ 反面教材、// 💀 埋雷点
• 正面案例明确标注 // ✅ 手术后

---

五、病案编号系统

本专栏所有坏味道 / 手法都用统一编号登记，形成跨篇索引。

5.1 编号约定

前缀	类别	编号范围	主要出没篇
N	Naming · 命名类	N01-N15	第 01、02 篇
F	Function · 函数类	F01-F20	第 01、05、09 篇
C	Class · 类与对象	C01-C18	第 02、09 篇
E	Error · 错误处理	E01-E10	第 02、10 篇
T	Test · 测试类	T01-T12	第 06、10、11 篇
A	Architecture · 架构类	A01-A15	第 07、12、13 篇
D	Debt · 技术债类	D01-D10	第 07、12 篇
R	Review · 代码审查类	R01-R08	第 11 篇

5.2 病案编号使用规范

• 首次出现：写作 [N01 · 神秘命名]，附一句话解释
• 跨篇引用：直接写 见 N01，读者可去索引页反查
• 每篇末尾：第 9 章"病案归档"必须列出本篇涉及的所有编号

5.3 病案卡片模板

每次介绍一个坏味道时，用统一卡片格式：

📋 病案编号：N01
📛 病名：神秘命名（Mysterious Name）
🔍 主诉：变量名 `r`、`data`、`temp` 让人看不懂
🩺 检查：字符搜索命中 3800+ 处，无法定位含义
💊 处方：Rename Variable（重构手法 6.7）
📖 出处：《重构》Fowler 6.7 / 《代码整洁之道》Ch2
🔗 关联病案：F01（隐晦命名的函数）、C03（模糊类名）

---

六、末章三件套

子节	内容	示例
10.1 病例真相揭晓	逐条回答第 1 章的疑问 ①②③④⑤⑥	"回到 OrderService.submitOrder 的 1247 行，6 个疑问现在能逐条作答了..."
10.2 一次完整手术记录	把本篇核心手法串成一次完整手术的时间轴	"Day 1 抽血化验 → Day 3 手术方案 → Day 7 手术台上 → Day 30 康复复查..."
10.3 设计哲学回扣	升华 3~4 条跨篇适用的设计原则	"命名即契约 / 边界即防线 / 测试即凭证 / 重构即呼吸"
10.4 速查表	一张可截图保存的速查表	本篇所有病案编号 / 坏味道 → 手法映射 / 度量对比

---

七、章节自检清单

写完一篇后，逐条对照：

• [ ] 第 1 章是真实病例吗？不是教科书例子？
• [ ] 第 1 章末尾是否列出了 5~7 个待解答的疑问？
• [ ] 第 2 章是否给出了坏味道的官方命名 + 病案编号？
• [ ] 第 5-7 章三医生查房是否关注面不同（不是深浅重复）？
• [ ] 每一位医生的查房末尾是否有"带走清单"？
• [ ] 第 8 章康复曲线是否有具体数据（不是"变好了"这种空话）？
• [ ] 第 9 章病案归档是否完整列出所有编号？
• [ ] 第 10.1 节是否逐条回答了第 1 章的疑问？
• [ ] 第 10.3 节是否提炼出可迁移的设计哲学？
• [ ] 全篇一级二级三级标题是否 6~9 字？
• [ ] 是否有过渡到下一篇？（"下一篇我们送来第二位病人..."）

---

八、章数与篇幅

项	推荐区间
总章数	10 章（固定）
每章节数	2~4 节
每篇总字数	1.2~1.8 万字
每篇总行数	700~1200 行（含代码、图、表）
代码 / 图 / 表占比	30%~40%

---

九、写作前置流程

flowchart LR
    A[选题·送来一位病人] --> B[写第1章·主诉+检查数据+5-7疑问]
    B --> C[第2章·给坏味道命名+登记病案]
    C --> D[第3章·追溯病因到代码/组织]
    D --> E[第4章·画手术总图]
    E --> F[第5-7章·三医生独立查房<br/>关注面不同]
    F --> G[第8章·康复曲线量化对比]
    G --> H[第9章·病案归档编号]
    H --> I[第10章·回扣案例+设计哲学]
    I --> J[自检清单逐项过]
    J --> K[更新 README 状态]

---

十、贯穿角色档

代号	身份	医院对应	立场
老陈	10 年经验技术负责人	主治医师（后期晋升主任）	系统性重构、量化技术债
沈总	15 年经验技术总监	主任医师	组织文化、系统架构
小李	3 年经验骨干	住院医师（后期晋升主治）	想改但怕改坏，测试覆盖率 4%
老王	8 年经验业务骨干	病人家属（业务方代表）	反对大重构，"能跑就行"
小张	应届生	实习医师	一片空白，边学边干
QA 阿玲	测试团队 lead	影像科主管	手工回归 3 天 → 目标半小时
产品娟姐	业务方	患者家属	每周都要上新功能

---

十一、贯穿病例档

病人代号	中文名	主要病症	出现篇章
P-001	OrderMonolith · 订单巨兽	God Class / 1247 行 / 圈复杂度 68	全部 14 篇
P-002	CouponCalc · 优惠券超发	硬编码 47 个 else if / 无测试	第 04、09 篇
P-003	StockDeduct · 库存超卖	无并发控制 / 无事务	第 03、10 篇
P-004	PaymentGate · 支付网关	吞异常 / 无幂等	第 03、10 篇
P-005	NextDaySvc · 次日达新系统	Greenfield 项目，如何"不生病"	第 12、13 篇

---

十二、参考标杆

第 01 篇 01.命名的战场.md 是本模板的完整范本（10 章 + 三医生 + 病案编号全覆盖）。新写文章遇到结构疑问时，优先回看 01 篇对应位置。

---

十三、专属专栏要求

要求	说明
每篇必有 before/after 对照	至少一段代码给出重构前后完整对比，行数指标要标注
每篇必有度量数据	圈复杂度 / 覆盖率 / 参数数 / 函数行数 / 事故数——不能只说"好多了"
每篇必有经典书出处	至少标注 1 本经典书籍章节：《代码整洁之道》/《重构》/《修改代码的艺术》/《Google 工程实践》等
每篇必有跨语言对照	关键手法给 Go / Python / TypeScript 至少一门对照，避免绑定 Java
每篇必有"练习题"	送给读者一段真实开源代码 / 团队代码，让读者自己诊断
每篇必有"下集预告"	用医院隐喻自然过渡到下一篇（"下一位病人已经在门外了..."）