software-design-philosophy

软件设计哲学

运用 John Ousterhout 的《A Philosophy of Software Design》第 2 版，降低理解和修改软件的成本。Brooks 的概念完整性是第二个支点。给出一个命名的设计或修复、其原因，以及下一步行动。

选择路径

工作	加载的方法
新模块，或影响重大的 API／接口形态	references/design-mode.md
修改现有代码，同时降低其复杂度	references/improve-mode.md
评估 diff、设计、PR 或 design-gate 输入	references/review-mode.md

对于没有边界决策的局部命名或结构清理，使用 clean-code；对于测试优先的执行，使用 tdd。通过所选技能继续完成请求的工作；选择合适的方法不构成新的审批关卡。

通用设计规则

使用以下关键词解释实际的设计决策：

• 战略性（strategic）——现在投入少量设计，让下一次修改更省力。反面是战术性（tactical，意为“先让它能用”）和战术旋风（tactical tornado，指通过快速交付却留下烂摊子的人）。
• 深模块（deep module）——接口简单，却隐藏了大量功能。成本在于接口；收益在于它所隐藏的内容。学习一个浅模块（shallow module）的成本，差不多与直接阅读其内联代码一样高。
• 信息泄漏（information leakage）——同一个设计决策体现在两个或更多模块中。这就是变更归属（change ownership）失败；应让一个地方负责此决策。
• 设计两次（design it twice）——对于影响重大的未决接口，在编码前比较两到三种有实质差异的形态。除非有新证据提出质疑，否则应复用已定的接口。
• 保持战略性（stay strategic）——修改现有代码时，不要添上让设计变差的特殊情况。让修改融入设计，或者改进设计。
• 确定关键事项（decide what matters）——明确当前情况所依赖的少数关键因素，尽量减少这些因素，并只突出它们。
• 读者，而非作者（reader, not writer）——复杂度由下一个修改代码的人来判断。如果代码只有你自己觉得简单，那它就是复杂的。
• 概念完整性（conceptual integrity）／最小连贯形态（smallest coherent shape）——只采用一种模型，且不超出问题所需。

示例句：“这是战术性做法——在一个浅模块上添加特殊情况。设计两次有助于保持概念完整性；现在多花一小时，胜过日后出现信息泄漏。”

官方摘录中的另一个示例句：“backspace(cursor) 是一种虚假抽象（false abstraction）——界面仍须知道哪些字符会消失。一个 delete(start, end) 更有杠杆效应（leverage）；那些特殊方法则没有。”

证据与权威依据

检查足够多的实际代码或给定设计，以识别抽象、非正式接口（调用方必须了解的一切），以及相关的警示信号或原则。只有在进一步阅读可能改变决策时才继续深入。没有代码仓库时，使用提供的约束，并标明假设。

请以读者，而非作者的角度思考：下一个开发者是否需要知道接口中未包含的信息？这说明存在信息泄漏或晦涩之处。复用已经确定的选择；只有在影响重大的设计决策尚未解决时才考虑替代方案，而不是每次局部修改都考虑。

review 和所有 design-gate 调用都只能读取：仅报告发现，不得编辑或运行测试。design 和 improve 可以在用户请求范围内编辑，但不授权进行无关重构。

在访谈中，应将边界决策、理由、约束和来源引用记录到现有的决策记录中。代码编辑、接口注释、测试实施细节和独立报告，应留待后续获准阶段处理。

验收约定

使用所选模式的输出字段。为每项发现指出其背后的官方警示信号或原则。报告实际被否决的替代方案，或说明无需作出新的设计选择。对于编辑，指出已更改的文件、保持行为不变的工作或具体的行为变化，以及已运行或无法运行的检查。

在 design-gate 下，使用调用方的规范门禁结果，并将概念完整性结论放入 review_focus。泄露的决策、肤浅的新公共接口或权宜的特殊处理，在其承载关键职责时可能构成阻止理由；表面命名问题仅作提示。

注意事项

1. 不要把一行代码的 Bug 修复变成设计练习。让投入与风险相称。
2. 当被破坏的模型本身就是需求时，不要保留现有模式。
3. 不要混淆一致性与概念完整性——一再一致地重复错误，仍然是缺陷。
4. 不要为了填满某个类别而凭空捏造发现。clean 是有效结果。
5. 不要引用或还原本技能所提炼的书中原文。
6. 深度优先于长度（第 9.8 节）。代码过了几十行后，缩短函数很少能改善系统。更多的小函数意味着更多接口和相互耦合的方法。不要用一个十个词的方法名替换一条恰到好处的注释。会泄露单一格式的小类通常是_类太多_——应将它们合并。
7. 不要把设计决策藏在提交消息里。注释应写在代码中。
8. private 加上 getter 并不构成信息隐藏。如果调用方必须知道该字段存在，它就在接口中。
9. 大量文档往往是难以描述的警示信号，而非优点。简化设计。

章节查找

所选模式会链接到所需的原则、警示信号和方法。只有在需要查找不符合这些路径的问题时，才加载 references/chapter-map.md。