# 软件设计框架的哲学用于管理软件工程的基本挑战的实用框架：复杂性。在设计模块、审查 API、重构代码或就架构决策提供建议时应用这些原则。中心论点是，复杂性是大多数软件问题的根本原因，管理复杂性需要在设计的每个层面进行深思熟虑的战略思考。 ## 核心原则 **编写软件的最大限制是我们理解我们正在创建的系统的能力。**复杂性是敌人。它使系统难以理解、难以修改，并且成为错误的根源。每个设计决策都应该通过以下问题来评估：“这会增加还是减少系统的整体复杂性？”我们的目标不是零复杂性——这在有用的软件中是不可能的——而是最大限度地减少不必要的复杂性，并将必要的复杂性集中在可以管理的地方。 ## 评分 **目标：10/10。** 在审查或创建软件设计时，根据是否遵守以下原则对它们进行 0-10 评分。 10/10 意味着具有清晰抽象的深层模块、出色的信息隐藏、对复杂性的战略思考以及捕捉设计意图的注释。较低的分数表示模块较浅、信息泄漏、战术捷径或缺少设计文档。始终提供当前分数以及达到 10/10 所需的具体改进。 ## 软件设计框架管理复杂性和生成易于理解和修改的系统的六个原则： ### 1\.复杂性及其原因 **核心概念：** 复杂性是与软件系统的结构相关的任何使其难以理解和修改的事物。它通过三个症状表现出来：变化放大、认知负荷和未知的未知。 **为什么有效：** 通过识别复杂性的具体症状，开发人员可以精确地诊断问题，而不是依赖于“混乱代码”的模糊概念。两个根本原因——依赖性和模糊性——为设计改进提供了明确的目标。 **关键见解：** * 变更放大：一个简单的变更需要多处修改 * 认知负荷：开发人员必须记住太多信息才能做出改变 * 未知的未知：不明显什么需要改变，或者什么信息是相关的（最糟糕的症状） * 依赖关系：代码不能被孤立地理解或修改 * 模糊性：重要信息从代码或文档中不明显 * 复杂性是渐进的——它是由数百个小决策累积而成，而不是一个大错误 *“千刀万剐”的复杂性意味着每一个决定都很重要 **代码应用：** 背景 |图案|示例 ---|---|--- **改变放大率** |集中共享知识 |提取颜色常量，而不是在 20 个文件中硬编码“#ff0000” **认知负荷** |减少开发人员必须了解的内容 |使用简单的“open(path)” API，而不需要缓冲区大小、编码和锁定模式 **未知的未知** |使依赖关系明确 |使用类型系统和接口来显示更改的影响 **依赖管理** |最小化跨模块耦合 |通过明确定义的接口传递数据，而不是共享全局状态 **降低模糊度** |准确地命名事物 | `numBytesReceived` 不是 `n`； “retryDelayMs”不是“延迟” 请参阅：[references/complexity-symptoms.md]() ### 2\.深模块与浅模块 **核心概念：** 最好的模块是深入的：它们在简单的界面背后提供了强大的功能。浅层模块具有与其提供的功能相关的复杂接口，增加而不是减少复杂性。 **为什么有效：** 模块的接口代表了它对系统其余部分施加的复杂性。它的实现代表了它提供的功能。深层模块为您提供了较高的功能与界面复杂性比率。接口就是成本；执行就是效益。 **关键见解：** * 模块的深度 = 提供的功能 / 施加的接口复杂度 * 深层模块：简单的接口，强大的实现（Unix文件I/O，垃圾收集器） * 浅层模块：接口复杂，实现有限（Java I/O 包装类） *“阶级炎”：创建太多小而浅的阶级的疾病 * 每个接口都会增加认知负担——更多的类并不意味着更好的设计 * 最好的抽象在一些简单的概念背后隐藏着巨大的复杂性 * 小方法并不一定是好的；深度比大小更重要 **代码应用：** 背景 |图案|示例 ---|---|--- **深度模块** |将复杂性隐藏在简单的 API 背后 | `file.read(path)` 隐藏磁盘块、缓存、缓冲、编码 **浅层模块** |避免使用刚刚穿过的薄包装纸 |包裹在“ObjectInputStream”中的“BufferedInputStream”中的“FileInputStream” **分类炎治愈** |合并相关浅类 |将 `RequestParser`、`RequestValidator`、`RequestProcessor` 合并为一个 `RequestHandler` **方法深度** |方法应该做一些实质性的事情 |处理锁定、日志记录、缓存失效和重新平衡的“delete(key)” **界面简单** |更少的参数，更少的方法 | `config.get(key)` 具有合理的默认值，而不是 15 个构造函数参数请参阅：[references/deep-modules.md]() ### 3\.信息隐藏和泄露 **核心理念：** 每个模块应该封装其他模块不需要的知识。当设计决策反映在多个模块中时，信息泄漏是软件设计中最重要的危险信号之一。 **为什么有效：** 当信息隐藏在模块内时，对该知识的更改只需要修改该模块。当信息跨模块边界泄漏时，更改会在系统中传播。信息隐藏减少了依赖性和模糊性，这是复杂性的两个根本原因。 **关键见解：** * 信息隐藏：将设计决策的知识嵌入到单个模块中 * 信息泄漏：相同的知识出现在多个模块中（危险信号） * 时间分解会导致泄漏：根据事情发生的时间来分割代码，迫使跨阶段共享知识 * 通过数据格式、协议或共享假设的后门泄露是最微妙的形式 * 装饰器是常见的泄漏源——它们暴露了装饰过的接口 * 如果两个模块共享知识，请考虑合并它们或创建一个封装共享知识的新模块 **代码应用：** 背景 |图案|示例 ---|---|--- **信息隐藏** |封装格式详细信息 | HTTP解析逻辑由一个模块负责；调用者获得结构化对象 **时间分解** |按知识而非时间进行组织 |将“读取配置”和“应用配置”合并到一个配置模块中 **格式泄漏** |集中序列化 |一个模块处理 JSON 编码/解码，而不是到处传播“json.dumps” **协议泄露** |抽象协议详细信息 | `MessageBus.send(event)` 隐藏传输是 HTTP、gRPC 还是队列 **装饰器泄漏** |谨慎使用深包装纸 |更喜欢在文件类内部添加缓冲而不是在外部包装它请参阅：[references/information-hiding.md]() ### 4\.通用模块与专用模块 **核心概念：** 设计“某种程度上通用”的模块：接口应该足够通用以支持多种用途，而不必与当今的特定需求绑定，而实现则可以处理当前的需求。问：“能够满足我当前所有需求的最简单的界面是什么？” **为什么有效：** 通用接口往往更简单，因为它们消除了特殊情况。它们的设计也面向未来，因为新的用例通常适合现有的抽象。然而，过度概括会浪费精力，并且本身会通过不必要的抽象引入复杂性。 **关键见解：** *“有点通用”是太具体和太通用之间的最佳点 * 关键问题：“能够满足我当前所有需求的最简单的界面是什么？” * 通用接口通常比专用接口更简单（特殊情况较少） * 降低复杂性：较低级别的模块应该处理困难的情况，因此较高级别保持简单 * 配置参数通常代表无法确定正确的行为——每个参数都是复杂性推给调用者的 * 如有疑问，请首先实施更简单、更通用的方法 **代码应用：** 背景 |图案|示例 ---|---|--- **API通用性** |为概念而设计，而不是为某个用例而设计|使用 `text.insert(position, string)` API 代替 `text.addBulletPoint()` **降低复杂性** |处理模块中的默认值 |一个 Web 服务器，可以选择合理的缓冲区大小，而不需要调用者配置它们 **减少配置** |自动确定行为 |自动检测文件编码，而不需要“encoding”参数 **避免过度专业化** |删除特定于用例的方法 |一个“store(key, value, options)”，而不是“storeUser()”、“storeProduct()”、“storeOrder()” **有点一般** |通用接口，具体实现 |当前支持 PostgreSQL 但不公开 SQL 概念的“Datastore”接口请参阅：[references/general-vs-special.md]() ### 5\.作为设计文档的评论 **核心概念：** 注释应该描述代码中不明显的事情。它们捕获设计意图、抽象原理以及无法用代码表达的信息。 “好的代码是自我记录的”这一说法对于低级实现细节之外的任何内容来说都是一个神话。 **为什么有效：** 代码告诉您程序做什么，但不告诉您为什么这样做、设计替代方案是什么，或者代码做出什么假设。注释捕捉了设计者的心智模型——抽象——这是系统中最有价值和最容易消失的信息。 **关键见解：** * 四种类型：接口注释、数据结构成员注释、实现注释、跨模块注释 * 接口注释是最重要的：它们定义了模块呈现的抽象 * 先写注释（注释驱动设计），在写代码之前理清思路 * “自记录代码”仅适用于低级内容；它失败的原因、假设和抽象 * 注释应该描述不明显的内容——如果代码说得很清楚，就不要重复 * 在其描述的代码附近保留注释；当代码更改时更新它们 * 如果注释很难写，则设计可能太复杂 **代码应用：** 背景 |图案|示例 ---|---|--- **界面评论** |描述抽象，而不是实现 | “返回最接近给定位置的小部件，如果阈值距离内不存在小部件，则返回 null” **数据结构评论** |解释不变量和约束 | “列表按优先级降序排序；平局按插入顺序断开” **实施意见** |解释为什么，而不是是什么 | “// 此处使用二分搜索，因为列表始终已排序并且可以包含 100k+ 项” **跨模块评论** |链接相关设计决策| “//此超时必须与RetryPolicy.java中的重试间隔匹配” **评论驱动的设计** |将接口注释写在代码之前 |首先起草函数的契约和行为，然后实施请参阅：[references/comments-as-design.md]() ### 6\.战略与战术规划 **核心概念：** 战术编程的重点是让功能快速运行，通过每个快捷方式积累复杂性。战略规划在良好的设计上投入 10-20% 的额外精力，将每次更改视为改进系统结构的机会。 **为什么有效：** 战术编程在短期内显得更快，但会逐渐降低代码库的质量，使未来的每一次改变都变得更加困难。战略性编程产生的代码库随着时间的推移很容易修改。少量的前期投资组合——战略性设计的系统在几个月后可以更快地使用。 **关键见解：** * 战术龙卷风：快速开发功能但留下残骸的开发者；经常庆祝短期但破坏性长期 * 战略思维：你的主要工作是产生一个恰好可行的出色设计，而不是恰好有设计的可行代码 * 10-20%的投资：花费大约10-20%的开发时间用于设计改进 * 初创公司最需要战略规划——随着团队的成长，早期的设计捷径会加剧技术债务 *“快速行动，打破常规”文化（早期的 Facebook）与注重设计的文化（Google）——Google 工程师在复杂系统上的工作效率更高 * 每次代码更改都是一次投资机会：让代码比您发现时更好一点 * 重构不是一个特殊的事件——它是每个功能开发的一部分 **代码应用：** 背景 |图案|示例 ---|---|--- **战术陷阱** |抵制快速而肮脏的修复|不要添加布尔参数来处理“仅此一种特殊情况” **战略投资** |在功能工作期间改进结构 |添加功能时，如果模块界面变得笨拙，请重构它 **战术龙卷风** |认识并干预|开发人员编写了 2 倍的代码，但造成了 3 倍的维护负担 **创业纪律** |从第一天起就投资设计 |即使在时间压力下也能保持清晰的模块边界和良好的抽象 **渐进式改进** |针对每个 PR 修复一个设计问题 |每个拉取请求至少改进了一个抽象或消除了一项复杂性 **设计评论** |评估结构，而不仅仅是正确性 |代码审查应该问“这会让系统更简单吗？”不仅仅是“它有效吗？” 请参阅：[references/strategic-programming.md]() ## 常见错误错误|为什么失败 |修复 ---|---|--- **创建太多小班** | Classitis 增加了界面，但没有增加深度；每个类别边界都是认知开销|将相关的浅层类合并到具有更简单接口的更深层次模块中 **按时间顺序分割模块** | “阅读，然后处理，然后写入”迫使三个模块共享知识|围绕信息进行组织：将共享知识的代码分组到一个模块中 **公开接口中的实现** |呼叫者取决于内部详细信息；变化无处不在|围绕抽象而不是实现来设计接口；隐藏格式和协议详细信息 **将评论视为可选** |设计意图、假设和抽象都丢失了；新开发者猜错了|先写接口注释；随着代码的发展维护它们 **一切的配置参数** |每个参数都会向调用者推送一个决定，从而增加认知负荷 |自动判断行为；提供合理的默认值；最小化所需的配置 **快速而肮脏的战术修复** |每个快捷方式都会增加少量的复杂性；随着时间的推移，系统变得无法工作|在良好的设计上额外投入 10-20%；将每一次变化视为设计机会 **传递方法** |仅委托给另一个方法的方法添加接口而不增加深度 |将传递合并到调用者或被调用者中 **针对特定用例进行设计** |专用接口积累特例变得臃肿 |问“满足当前所有需求的最简单的界面是什么？” ## 快速诊断问题 |如果没有 |行动 ---|---|--- 你能用一句话描述一下每个模块的作用吗？ |模块做得太多或用途不明确 |分成具有连贯的、可描述的职责的模块接口比实现更简单吗？ |模块很浅——它们向外泄漏复杂性|重新设计以隐藏更多；将浅层的类合并到更深的类中您可以在不影响调用者的情况下更改模块的实现吗？ |信息跨模块边界泄漏 |识别泄漏的知识并将其封装在一个模块中接口注释描述的是抽象，而不是代码吗？ |设计意图丧失；开发人员会滥用该模块|编写注释来解释模块的承诺，而不是它的工作原理设计讨论是代码审查的一部分吗？ |评论只能发现错误，不能发现复杂性增长 |添加“这会降低还是增加系统复杂性？”审查标准每个模块是否隐藏了至少一个重要的设计决策？ |模块是围绕代码而不是信息组织的 |重新组织，使每个模块都拥有特定的知识新团队成员可以在不阅读实现的情况下理解模块边界吗？ |抽象没有记录或泄漏太多 |完善界面注释，简化界面，直至不言而喻您是否花费 10-20% 的时间用于设计改进？ |每一项功能的技术债务都在不断累积采取战略思维；在每个 PR 中都包含设计改进 ## 参考文件 * [complexity-symptoms.md]()：复杂性的三个症状，两个原因，测量复杂性，复杂性的增量性质 * [deep-modules.md]()：深层与浅层模块、接口与功能比、分类、深度设计 * [information-hiding.md]()：信息隐藏原理、信息泄漏危险信号、时间分解、装饰器陷阱 * [general-vs-special.md]()：有点通用的方法，降低复杂性，配置参数反模式 * [comments-as-design.md]()：四种注释类型、注释驱动设计、自记录代码神话、维护注释 * [strategic-programming.md]()：战略与战术思维、战术龙卷风、投资方法、启动注意事项 ## 进一步阅读该技能基于 John Ousterhout 的软件设计实用指南。有关包含详细示例的完整方法： * [_“软件设计哲学”_]() 作者：John Ousterhout（第二版） ## 关于作者 **John Ousterhout** 是斯坦福大学计算机科学系 Bosack Lerner 教授。他是 Tcl 脚本语言和 Tk 工具包的创建者，并共同创立了包括 Electric Cloud 和 Clustrix 在内的多家公司。 Ousterhout 获得了众多奖项，包括 ACM 软件系统奖、加州大学伯克利分校杰出教学奖和 USENIX 终身成就奖。他从斯坦福大学的 CS 190 课程中发展出了“软件设计哲学”，学生们在该课程中从事多阶段软件设计项目，并学习识别和降低复杂性。本书将数十年构建系统软件和教学软件设计的经验提炼成一套简明的原则，适用于各种语言、范式和系统规模。现在，这本书已出版第二版，已成为软件工程师广泛推荐的资源，以提高他们的设计技能，超越正确性并提高清晰度。

软件设计理念

包含技能