跳到主要内容

审查 principles-of-programming — 2026-08-29

结论: ISSUES(4 条:1 major / 2 medium / 1 minor)

门禁实跑:

  • node scripts/book-verify.mjs principles-of-programming → book-verify: 1 本有拆解、共 964 处出处、0 处对不上
  • node scripts/book-jargon.mjs principles-of-programming → book-jargon: 1 本,共 0 处专业词没解释就用了
  • node scripts/book-jargon.mjs principles-of-programming --quota → 生面孔配额:段级超额 0 处(上限 1)、节级超额 0 处(上限 5)
  • node scripts/book-dodged.mjs principles-of-programming → book-dodged: 1 本,共 0 个词被躲开(阈值:原书出现 ≥15 次)

问题清单​

  1. [index.md §4「覆盖」栏 — major] 覆盖声明不实:18 条原则静默丢弃,且未照 201-principles 先例在 notCovered 点名。 index 声称「101 条全部落位,每条主线讲透因果;每章末尾的原文地图可回查原书条目」。逐条对照原书目录 (library/principles-of-programming/text/03-fm.txt,101 = 1章3 + 2章7 + 3章64 + 4章6 + 5章6 + 6章6 + 7章9) 与全组正文 + 全部原文地图表 grep,以下 18 条在拆解中零出现(正文、frontmatter、原文地图、notCovered 四处皆无): 3.17 充足性完整性原始性、3.20 单一引用点、3.21 分治、3.22 软件架构的非功能需求、3.24 互操作性、 3.26 可靠性、3.27 可测试性、3.28 可复用性、3.29 七个设计原理(其下 3.30 简单性/3.31 同构/3.32 对称原理/ 3.33 层次原理/3.34 线性原理五条均未展开)、3.59 可移植性优先于效率、5.6 TMTOWTDI、 6.4 内部测试(原书实为 Dogfooding「吃自己的狗粮」,不是单元测试)、7.6 约书亚树原则。 另有 4 条属于「机制已讲、名字未挂」:3.20 被 03 章写法 C/OFOP 吸收、3.33 层次原理被 05 §4 层次化吸收、 3.12 抽象只在 04 原文地图有一行、3.23 易变性在 06 只有地图行正文未展开。 — 违反:收尾自检「完整性:原书每一章都被覆盖了吗」;201-principles 先例(index §4 明写「约 190 条进了正文, 个别次要条目未逐条展开,见下表」并列出 8 条名字)。汇编重组允许取舍,不允许声称全落位。 — 修:①把「101 条全部落位」改为实数(约 83 条展开);②「不覆盖」表照 201 先例加一行,点名上述 18 条 (每条给原名+一句话去向);③3.20/3.33 这类机制已讲的,在 03/05 对应处补一句原则名挂靠即可转为「落位」。

  2. [09-daily-craft.md:8 / 10-people-and-prophecy.md:8 frontmatter — medium] sourceChapters 虚列。 09 列了「6.4 内部测试」,10 列了「7.6 约书亚树原则」,但两章正文对这两个原书小节零展开、零脚注、零地图行 (grep 全文仅 frontmatter 命中)。sourceChapters 是完整性审计与 agent 跳转的依据,列了不讲等于造假账。 — 违反:「sourceChapters = 这一章拆的是原书哪几章」的字段约定(BOOK-TEARDOWN frontmatter 表)。 — 修:从两处 sourceChapters 删掉这两项;或者各补一小段(7.6「知道名字才看得见东西」与 02 章命名一节 天然契合;6.4 Dogfooding 与 09 章原型/真实反馈一节天然契合),补上则问题 1 的名单同步缩短。

  3. [index.md §4 — medium] 与姊妹书的分工没讲清。 任务与书卡都要求讲清三分工,实际:the-missing-readme(职场向)在全组 11 份文档里零提及; 201-principles(管理向)只在书卡 aiRef/sources/principles-of-programming.md 里讲了「201 管理侧、本册代码侧」, 拆解站内仅 02 章一处「定量数字见《软件开发的 201 个原则》」顺带一指,读者在文档站上得不到这张分工图。 — 违反:总纲「覆盖什么/不覆盖什么」应尽的指路职责(本次审书任务明列项)。 — 修:在 index §4 不覆盖表加两行:管理侧(估算/需求/人员)→ 201-principles-software-development; 文档怎么写给同事(README/沟通)→ the-missing-readme;本册管代码侧原则。

  4. [各章 frontmatter — minor] sourceChapters 章名与 chapters.json 不一致。 01/10 用的是 chapters.json 原章名(「序章　本书导读」「后记」),其余各章用原书小节名(如「4.1　内聚度」 「2.4　PIE」),06 还写了「3.23　易变性(软件老化)」这类原书没有的括号补语。因原书第 4–7 章是整文件 (chapters.json 只有「第4章　视角…」),用小节名有实际理由,但严格按「章名与 chapters.json 一致」的约定 机械对照时对不上。— 修:统一成 chapters.json 章名 + 在括号里附小节号(如「第4章　视角(4.1–4.3)」), 或在 notes 里记一条口径说明,免得下一轮审计重查一遍。

核过且过关的项(对应收尾自检)​

  • 出处:四门禁全绿(964 处 0 错);另抽 7 条脚注亲自回核原文,全部属实: 01[^9] (05-ch01.txt:45 认知→需求)、03[^23] (06-ch02.txt:348 简单方案通用性更强)、 05[^19] (71-ch04.txt:425 HTTP GET)、07[^22] (73-ch06.txt:459 正当性/坚固性)、 10[^19] (74-ch07.txt:65 妊娠比喻)、06[^22] (74-ch07.txt:222 信箱实验 25%)、 08[^13] (67-ch03-61.txt:25 伟大的程序员能借来好的代码)。
  • 主走查(抽 2 章细核 + 全 10 章普查):10/10 章主走查都在正文、都标了「演示数值」或「书里原例」。 04 税法走查(放法一/放法二逐步,效应局部化→变动率→单一职责各占一步,机制落不到走查的由 §6 总图收拢) 与 05 全局变量 X 事故链(书里原例四步,每步有具体状态,收束到「结构让他看不见 C」)合格。
  • 汇编重组裁断(抽 2 条主线):DRY/KISS/YAGNI 主线(03)因果链完整——重复=每次修改交税(三连锁困难、 细微差别使替换不安全)→抽象化收敛(当期成本与长期收益)→失效边界(偶然的共同、阻抗失配消不掉、 YAGNI 与可扩展性的「免罪符」分界);OCP 主线(04)——「先挨第一发子弹」「猜部位不猜内容」讲透了 原则为什么成立、何时失效。读完能复述、能说出边界。
  • 判断块:全组 4 个(index 3 + 01 章内 1)全部带「如果错,会错在」;各章「作者的判断与证据」节 均把书内证据与作者推测分开标。
  • 总纲:主线节(§2,①–⑪)可独立成篇,海拔合规(效果句+因果,机制退回章节,「第 N 章讲」逐条挂账); 兑现表 31 行,抽 3 行(10 §1 热点、07 §2 契约、09 §1 原型)全部兑现且是许诺的那件事。
  • 生词/配额/躲词:机器全绿 + 抽读无「一段多词」体感;编译器、断言、接口、幂等、熵等承重词均就地解释。
  • 台阶:抽 02 §1–2、04 §5 段首句连读不跳;先现象后原理(01 §1 卡坎、06 §1 房间生肉)执行到位。
  • 红线一:抽比 06 §1 熵增引文、09 §4 高强度工作 blockquote 与原文,均为压缩改写+短句引用,无整段搬运。
  • 台账:页面正文无格式/许可/清洗统计;index 页脚「原始书籍文件不入库…可回核」写法与已验收样板 what-is-chatgpt-doing 一致,不判违规。TODO(没懂) 零命中。
  • 书卡:readState/read 全章、claims 8 条与拆解一致、notCovered 5 条、soWhat 已填; 唯「第3章 思想(3.1–3.64 全部)」的「全部」读法与问题 1 相关,修 index 时书卡 claims 无需动。