Code Style 是一个面向已有代码库的编码规范技能,核心是四条按优先级排列的原则:存在(Exist)、复用(Reuse)、模仿(Mirror)、对称(Symmetry)。当两条原则冲突时,靠前的原则优先。
一、确认代码需要存在
写新代码前先确认它确实需要存在。删除或收窄优于新增。一个只有单一实现的抽象、只有一个调用方的配置点、调用方无法到达的分支、为预期需求搭建的脚手架,都属于可以丢弃的工作。删除已有代码前,应先追踪其调用方,确认没有依赖该行为。新增测试同样需要证明其价值:在添加之前,说明它保护的行为,以及会使它失败的可信回归场景,并确认没有现有测试已在该回归上失败。若现有测试覆盖同一契约,应扩展其用例。测试应通过生产代码已有的边界驱动,而不是新增只有测试调用的导出、标志或钩子。但输入校验、防止数据丢失的错误处理、安全控制、无障碍支持以及明确请求的内容,优先级高于本规则。
二、复用现有代码
写新辅助函数前,先检查现有方法是否可以复用或泛化。如果确实需要新辅助函数,应参照其最接近的同类进行建模。
三、复用现有模式
找到最接近的类似功能并复刻其结构,包括方法拆分、控制流、注解、守卫子句。当现有模式适用时,采用它而不是引入新模式。如果遵循现有模式会导致明显更多的代码或间接层,可以采用不同方案,但应在整个改动中一致应用。
四、精确模仿周边代码
先阅读附近代码,然后匹配括号风格、注释风格、命名约定、空行间距、代码密度和细节程度。
五、保持对称
如果新增 fooB() 与 fooA() 平行,应匹配命名、参数顺序和结构。对称性覆盖新增同类所涉及的所有命名:标识符、路由路径、配置键、事件名、环境变量、CLI 标志和文件命名方案。默认应重命名既有名称;仅当它是无法更新消费者的已发布契约,或无法与重命名同步更新时才保留原样。部署和注册视为本次改动应承担的成本:更新所有引用或注册该名称的位置属于改动的一部分。
六、逻辑顺序
新增方法、switch 分支和字段应放在镜像现有分组或业务生命周期的位置,而不是追加在末尾。
七、默认不写注释
通过命名、抽取和结构让代码自解释。想写注释时,先尝试重构使其变得不必要。仅在存在代码无法表达的承重约束时才添加,例如隐藏不变式、变通方案或非显而易见的性能特征。存疑时省略。
适用场景:在既有代码库中编写新代码、添加新功能、扩展现有测试时。限制:该技能描述的是编码原则,未提供具体的平台支持、收费信息、价格或安装步骤。