工程原则 是做什么的?
构建最小、正确、且易于理解和安全变更的解决方案。将原则视为推理工具,而非凌驾于需求、代码库约定或证据之上的法则。
工作循环
- 建立契约。 阅读相关代码、调用方、测试和代码库说明。确定所需的行为、输入、输出、不变条件、失败模式和兼容性约束。区分观察到的事实与假设。仅当未解决的必需需求实质上会改变解决方案时才提问。
- 选择适当的设计。 重用本地模式和现有能力。倾向于直接实现;当需要处理真正的复杂性或保护实际的边界时再添加结构。在变更涉及之处考虑安全性、数据完整性和资源限制。
- 逐一处理关注点。 保持差异的凝聚性。保留无关的工作。将保留行为的重构与有意的行为变更分开,以便每个部分都可审查。修复原因,而不仅仅是观察到的症状。
- 验证承诺的行为。 使用最有意义的测试或可执行场景,包括相关的失败路径。检查实际运行的内容;空测试选择不能证明任何事情。通过的测试是其所断言的路径的证据,但不是所有正确性或兼容性的证明。
- 完成变更。 更新受影响的调用方、契约和文档。删除本次变更已废弃的代码。简要报告结果、验证结果以及任何剩余限制;仅当原则对决策产生了实质性影响时才解释原则。
根据风险级别调整此循环:局部重命名几乎不需要什么仪式;共享API或持久化数据变更需要消费者和迁移证据。对于常规编辑,不要制造设计文档或专家链。
调试与代码库工作流
将用户报告的失败视为可复现的问题;不要仅仅为了确认而要求他们重复。将观察到的行为与假设分开,然后收集区分可能原因的证据。使用聚焦的复现、有针对性的检查或调试器,而不是凭猜测更改代码。修复原因,保留有用的诊断信息而不泄露机密,并且永远不要抑制错误以使路径看起来成功。当失败可能导致部分状态时,添加缺失的回归覆盖并验证相关的恢复行为。
使用代码库现有的构建、测试、运行和生成入口点。阅读其文档化的前置条件并调用人类和CI使用的相同命令;不要添加第二个工具链或在代码库已有其他合适接口时要求使用Make。没有匹配测试的测试命令不是证据。
维护有用的贡献者文档:保留代码本身未解释的“为什么”、不变条件和关键流程;更新受影响的文档,根据受众选择用户参考、教程或故障排除材料。避免与变更无关的广泛文档重写。
设计原则
正确性始于契约
在选择模式之前定义必须保持为真的内容。使用合适的类型、构造函数和显式状态转换使无效状态难以表示。保持可变状态的所有权和资源生命周期清晰。
在边界处验证不受信任的输入。不要仅仅因为看起来像是防御性代码就删除检查:要确定该条件是不可能的、已经得到保证,还是仍然是一个真正的失败模式。保留有用的错误上下文而不泄露机密。永远不要将失败伪装成成功的假象。
简单性:KISS 和 YAGNI
KISS 意味着最小化维护者必须理解的复杂性,而不仅仅是减少代码行数。YAGNI 意味着实现当前需求,而不是推测性的未来特性。两者都不能成为缺失错误处理、不安全的存储或不可维护的捷径的借口。
在没有当前需求的情况下,避免使用插件、通用框架、配置层或扩展点。简单的设计仍然可以有清晰的边界,使后续变更成本低廉。
系统范围的复杂性
区分本质复杂性(问题本身所需)、可选复杂性(具有成本的能力)和意外复杂性(实现指定行为时可避免的困难)。将这些作为推理类别,而不是特性配额。将它们应用于实现、接口、集成以及用户的努力和错误风险:降低一处的成本可能会将其转移到别处。消除意外复杂性;保留可选能力,当其用户价值证明了其全生命周期成本时。在截止日期下,比较当前的交付价值与端到端的努力、支持和维护;较少的代码行或特性本身并不能证明总成本更低。示例请参见 复杂性、接口和性能。
内聚、耦合和信息隐藏
将因相同原因而变更的代码分组;将独立变更的关注点分开。将易变的实现选择隐藏在一个小型、连贯的接口之后。倾向于执行有用工作的深层模块,而不是一系列透传包装器。
在能够让共享机制服务可识别的调用方且不嵌入某个调用方策略时,接口可以稍微通用一些。保持其通用性不超过当前用途所证明的程度:猜测的未来需求可能会给当前调用方带来负担。当其契约确实是特定的时候,选择专用接口。
单一职责关注的是变更的连贯原因,而不是每个类一个方法。低耦合意味着消费者几乎不需要了解内部细节,而不是每次调用都需要一个接口。保持依赖方向明确,并在实际可行时避免循环。
抽象与 DRY
DRY 意味着知识的权威表示只有一个,而不是消除所有看起来相似的序列。当调用方表达相同的规则并且应该共同演化时共享逻辑。当表面上相似的代码属于不同的概念或生命周期时,保持其分离。
当知识也出现在生成的文件中时,确定其权威源和生成器。在重新生成之前保护无关的编辑;解决重叠的所有权问题,而不是覆盖用户的工作。更新源,运行现有的生成器,并检查生成的差异。不要手动编辑生成输出作为持久的修复,也不要为琐碎的工作添加生成机制。
在提取之前,确定共享契约、变更的预期原因以及抽象所消除的复杂性。不要使用数值重复阈值作为证据。少量的重复可能比错误的耦合成本更低。
SOLID 作为诊断性问题
在设计中获益时使用这些问题;不要将面向对象的架构强加于过程式或函数式代码。
- 单一职责: 这个单元是否混合了独立变更的关注点?
- 开闭原则: 是否存在一个经过验证的、值得隔离的变异轴,而不是一个假设的扩展框架?
- 里氏替换: 一个实现能否替换另一个而不会通过更强的前提条件、更弱的保证或不兼容的失败让调用方感到意外?
- 接口隔离: 消费者是否仅依赖于他们使用的功能?
- 依赖反转: 一个稳定的策略是否应该依赖于一个狭窄的契约,而不是易变的I/O细节?函数或参数可以提供这种结合点;类层次结构不是必需的。
当继承不能建模真正的可替换关系时,优先选择组合而不是继承。使用语言惯用机制,而不是将模式名称作为目标。
可读性与最不意外原则
选择能够揭示领域含义、单位和所有权的名称。使控制流和副作用易于跟踪。使用注释来解释理由、约束和非显而易见的保证,而不是叙述明显的语句。
遵循代码库约定,除非它们导致了具体问题。函数大小、参数数量和嵌套深度是警告信号,而不是普遍的数字限制。额外的间接层并不自动意味着更清晰的代码。注释可以保留理由、约束和代码本身无法解释的抽象;根据上下文判断其价值,而不是为了满足长度或注释计数规则而删除它们或拆分连贯的逻辑。
依赖与性能
重用维护良好、适用于困难既定能力的库,特别是加密和协议处理。评估适用性、安全性、许可证、兼容性、运营成本和依赖重量。不要为了语言或代码库已经提供的琐碎操作而添加依赖。
为预期的输入大小选择合理的数据结构和算法。避免明显的冗余工作以及浪费的分配或复制。在复杂的优化之前测量怀疑的瓶颈;对代表性工作负载进行基准测试并保护正确性。命名工作负载、指标、基线、目标和停止准则;使用与实际用户或系统结果相关的度量,而不是活动计数。一旦满足契约或进一步收益不值得增加复杂性和维护成本时停止。确定契约重视延迟、吞吐量还是资源使用:批处理可以提高吞吐量,但同时可能恶化响应时间。不要为了样式上的简单性而牺牲声明的延迟或内存需求。示例请参见 复杂性、接口和性能。
Unix 哲学的实践
编写内聚的组件,它们做好一件事并通过显式契约进行组合。这不需要每个函数一个进程、微服务、纯文本存储或处处无状态。具有清晰API的内部库同样可以组合。
- 将机制与策略分离。 在分离降低耦合的情况下,使可重用的计算独立于表示、环境和不断变化的业务选择。
- 为组合而设计。 避免隐藏的全局状态和不必要的硬编码路径。使依赖和效果显式化;在适当的情况下让调用方选择目标。
- 倾向于可检查的表示。 使用简单的数据结构和文档化的格式。文本对于可互操作的工具很有价值;当保真度、数据量或性能要求时,二进制格式是有效的。
- 保持普通操作安静,失败可见。 静默意味着不相关的噪音,而不是缺少结果数据或抑制诊断。
- 重用工具。 倾向于现有可靠的能力而不是重新构建它们。当自动化用于脚本时,保持其非交互性。
根据接口的人类和机器消费者选择接口风格,而不是传统。函数或库API、稳定的CLI或过滤器适用于机器调用方和可重复的工作;人类任务可能需要可发现性、反馈或直接交互。如果两者都是真正的消费者,将领域逻辑与可选包装器分开,以便它们共享行为而不使GUI成为必需。遵循满足契约的最简单风格。有关实际权衡,请参见 Unix 接口 和 复杂性、接口和性能。 对于CLI、管道和配置设计,请阅读 Unix 接口。当复杂性、接口风格或性能权衡对决策产生实质性影响时,请阅读 复杂性、接口和性能。对于相互竞争的原则和示例,请阅读 权衡。这些参考是有条件的;对于无关的局部编辑,它们都不是强制性的。 有关实际调试、项目命令、生成的工件、维护者文档和依赖评估示例,请阅读 调试与维护。
安全演化与验证
重构保留可观察的行为,包括输出、错误、副作用和消费者依赖的契约。不要在重构期间静默修复怪癖。有意的契约变更应显式地更新受影响的测试和消费者;被取代需求的测试不是永久约束。
使用行为驱动的测试保护公共边界。重用足够的覆盖;当重要路径未被保护时,添加回归或特征化测试。在可行的情况下优先使用真实实现或聚焦的伪造,但使用测试替身来隔离真正成本高昂、非确定性或不安全的边界。避免对私有方法调用或确切的源代码措辞进行断言,除非这些本身就是契约。
检查有意义的边界情况:格式错误的输入、空数据、资源失败以及相关的并发或部分写入。不要为每次编辑规定任意的覆盖百分比或完整的测试套件。
除非改变范围中明确包含,否则保持公共兼容性。对于持久契约和持久化数据,检查消费者、部署顺序、迁移和恢复。当旧版本和新版本必须共存时,使用扩展/收缩或其他分阶段的方法;否则,协调的原子变更可能就足够了。在没有实际需求的情况下,不要删除恢复路径或安装兼容性垫片。
最终决策检查
在宣布完成之前,问自己:
- 实现是否满足实际契约,包括相关的失败?
- 每个抽象、依赖和更改的文件是否由此任务证明合理?
- 维护者能否找到规则、其状态所有者以及保护它的证据?
- 我是否保留了现有行为,还是已经显式地告知了跨受影响消费者的预期变更?
- 我实际验证了什么,还有什么未验证?
私下使用此检查;不要为每次编辑发出模板化的报告或原则评分。