codebase-stewardship

代码库维护

让下一次变更融入现有代码库。

先了解本地模式

添加新行为前，检查附近或类似的代码，了解：

• 命名风格和领域术语。
• 文件位置和公开导出。
• 数据流和状态归属。
• 错误处理和验证风格。
• 测试风格和测试固件约定。
• 现有扩展点或抽象。

即使其他模式单独来看也合理，也应优先遵循本地模式。

避免并行系统

除非任务明确要求替换旧方案，否则不要创建第二种方式来实现同一件事。

警示信号：

• 新辅助函数与现有辅助函数功能重叠。
• 新服务、钩子、适配器、命令或组件重复了现有职责。
• 新代码为同一概念采用了新名称。
• 新配置或标志绕过了现有功能。
• 附近的测试已使用共享测试固件，新测试却需要自定义设置。

如果存在重叠，应扩展或调整现有接口，而不是创建相互竞争的路径。

保持领域概念稳定

更改名称就是更改系统的语言。只有在请求要求重命名，或旧名称对当前变更确实具有误导性时，才进行重命名。

以下内容应使用现有领域术语：

• 类型和接口。
• API 字段。
• 事件和命令。
• 测试名称。
• 错误名称。
• 文件和目录名称。

如果需要引入新术语，应说明它与现有词汇的关系。

留下便于审查的依据

当变更引入新模式或扩展旧模式时，应让这一决策易于审查：

• 指明所遵循的现有模式。
• 说明为何应在该处进行扩展。
• 确保示例和测试使用一致的词汇。
• 避免将维护决策与无关的清理工作混在一起。

完成标准

变更应符合现有代码库的特性：遵循最接近的本地模式，避免重复系统，除非必须重命名，否则保留领域词汇，尽可能扩展现有接口，并使任何必要的新模式明确且易于审查。