SuperAPI AI 工具集

aposd-maintaining-design-quality

编程与开发

查看项目

更新于 10-16 10:14

技能介绍

该技能用于在修改现有代码时强制实施“战略性编程”纪律。其根本观点是:工作代码还不够好,如果改动没有让设计变好,通常就在让设计变坏;对设计恶化采取零容忍,因为“小妥协”会不可见地累积,大量战术决策最终形成难以维护的系统。

用途与适用场景

适用于任何需要修改既有代码的场景,尤其当改动属于新功能、重构或多文件修改时,技能要求走完整工作流。它把改动按紧急等级分类,让分析投入与影响相匹配:

  • 无关紧要:拼写修复、空白调整、注释更正,直接做即可。
  • 次要:少于 5 行的缺陷修复、配置微调、依赖升级,快速检查是否干净契合即可。
  • 标准:新功能、重构、多文件修改,需完整走 STOP-ASK-DECIDE-VERIFY。

战略修改工作流

修改现有代码前:

  1. 抑制“快速修复”的诱惑。
  2. 询问:“鉴于我需要的改动,当前系统设计是否仍是最佳?”
  3. 如果否:先重构,使系统达到“如果一开始就考虑此需求会具有的结构”。
  4. 如果是:在现有设计内改动,但确认改动是否干净契合。
  5. 提交前:扫描所有改动,确认文档反映了变化。

投资心态

技能认为战术式做法短期快 10-20%,长期永久变慢(生产率下降 20% 以上);战略式做法短期慢 10-20%,数月后获益并最终“免费”。建议将约 10-20% 开发时间用于设计改进。其推理是:快速修复不断累积复杂性,最终系统难以理解和修改,开发永久变慢;而战略路径中每次改动都改善或维持设计,过去投资为未来投资节省时间,最终加速开发。

设计演化原则

系统设计无法在最初就正确构想;成熟系统的设计更多由演化过程中的改动决定,而非初始构想。因此每次修改都重要——你的改动就是设计。

重构看似不可行时

即使期限紧张,也要问:“在当前约束下,这是我能做到的最好清洁设计吗?”若大规模重构不现实,寻找几乎同样干净但更快的替代方案;若暂时无法彻底清理,建立责任计划;若重构造成不兼容,寻求折中。绝不可接受的是:让设计变坏却没有修复计划。

延后重构的责任机制

若延后重构,必须追踪:

  1. 创建有具体范围的事项/工单。
  2. 限时:必须在 2 个迭代(或等价周期)内处理。
  3. 添加代码注释:// TODO(YYYY-MM-DD): [ticket-id] - [what needs fixing]。
  4. 同一区域存在 3 次以上延后则升级,重构成为强制。

没有这些步骤的“以后再做”等于不会做。

不应重构的场景

技能列出若干不应重构的情况:

  • 切斯特顿栅栏式代码:看似糟糕但处理微妙边界,先调查“为什么”再改。
  • 性能关键路径:干净抽象会带来开销,应记录其有意的“丑”。
  • 受监管/审计代码:改动触发昂贵的重新认证,先获明确批准。
  • 无测试的遗留代码:无测试重构危险,先加测试或冻结。
  • 依赖外部怪癖的代码:其他系统依赖未记录行为,需与依赖方协调。
  • 接近生命周期末期的系统:投入是浪费,记录即可,不要改进。
  • 事故响应期间:改动越多爆炸半径越大,只做最小修复。
  • 不熟悉领域时:“更好的设计”可能反映误解,先学习再重构。

关键问题:我是否理解代码为何如此?

紧急绕过标准

只有同时满足以下全部条件才可跳过正常流程:

  1. 生产环境此刻宕机(不是“可能很快出问题”)。
  2. 用户正受影响、安全泄露进行中或正在发生数据丢失。
  3. 修复极小(回滚或单行改动)。
  4. 承诺 24 小时内回来做正式实现。

紧急不意味着:“30 分钟后演示”(规划失败)、“CEO 在问”(权威压力不等于紧急)、“团队被阻塞”(他们可以等你思考)、“我们需要快”(速度压力正是最需要纪律的时候)。

红旗信号

技能列出若干红旗:快速修复心态(“先能用就行”)、复杂性蔓延(增加特例、条件、依赖)、补丁堆叠(补丁上叠补丁)、战术龙卷风(飞快开发者留下一团乱)、注释过期、延后清理(“以后重构”)等,分别提示设计将退化、技术债累积、他人为其速度付出代价等问题。

反合理化

技能提供多组“诱惑捷径—为何感觉对—为何错”的对照,包括“先能用就行”“别动能跑的代码”“以后重构”“这只是快速修复”“我没时间”“没那么糟”;责任回避类如“我不是这个模块的负责人”“原作者就是这么写的”“这符合现有模式”;以及“这不算”类如“这是临时/实验代码”“测试通过了”“我会记录技术债”。它强调:碰了就有责任;原始作者可能错了或上下文已变;一致遵循坏模式会扩散问题;临时代码往往最永久;测试通过不等于设计好;记录文档不等于修复。

注释维护

修改代码时保持注释同步:注释应靠近所描述代码、避免重复文档、每个决策只记录一次、找最明显的位置、提交前扫描所有改动以尽早发现过期注释。

技术债现实

技能指出:多数技术债永远不会完全偿还;“公平交易”实际偿还超过借入;“就这一次”一旦开始难以改变;“大家都这么做”会让复杂性迅速累积。

快速参考

每次修改现有代码时:

  1. STOP——抑制快速修复诱惑。
  2. ASK——“这个设计对我所需仍是最佳吗?”
  3. DECIDE——设计最优则干净改动;需改进则先重构;暂不能重构则计划何时做。
  4. VERIFY——注释更新了吗?设计改善或维持了吗?
  5. COMMIT——只在设计更好或至少不变差时提交。

规则:“如果你没有让设计变好,你很可能在让它变坏。”投资算术:现在慢 10-20% → 永远更快;“快速修复”现在 → 永远慢 20% 以上。