engineering-quality

工程质量

优先编写读起来平实、易于调试且不易被误用的代码。

清晰优先于巧妙

首先要优化的是让下一位维护者容易理解。稍长一些的实现通常更好，因为它能清楚展现名称、中间值和控制流。

在选择巧妙的抽象或紧凑表达式之前，先问问：

• 这解决的是当前问题，还是一个假想中的未来问题？
• 直接实现是否更容易审查？
• 这个抽象是在隐藏真实的复杂性，还是只是在转移复杂性？

注释解释原因，而非内容

注释应说明代码无法表达的背景：

• 不明显的业务决策。
• 安全或隐私约束。
• 性能方面的权衡。
• 规避问题的变通方案，以及它要避免的问题。
• 出乎意料的顺序要求。

删除复述下一行代码的注释。应改进命名或结构。

让故障便于调试

错误应指出失败的操作和重要背景，但不得泄露机密或敏感数据。

错误信息应尽可能回答：

• 系统当时试图做什么？
• 哪个稳定标识符或输入很重要？
• 这是无效输入、状态缺失、访问被拒，还是外部故障？

将特定于传输的错误类保留在传输边界。较低层的代码应抛出领域或应用错误，以便向外转换。

让局部重构不超出授权范围

只有在确保正确性或让变更路径更易理解时，才进行小范围的路径内重构。有关必要的局部支持与顺带改进之间的区别，请遵循 /agentic-change-governance；仅仅因为改动位置相近，并不代表获得了授权。

除非明确提出要求，否则应推迟可选的清理、范围扩展以及改动行为之外的工作。

留意算法形态

对十个条目适用的代码，在生产规模下可能会崩溃。将嵌套循环、重复查询、重复解析和广泛的数据获取视为设计决策。

如果实际操作涉及重复查找或匹配，则优先考虑使用映射、集合、索引、批处理或预计算。

完成标准

代码清晰易懂，无需破解技巧即可审查；注释只解释不明显的背景；错误包含有用且安全的上下文；必要的路径内重构不超出已接受的范围；算法形态适合预期规模。