SuperAPI AI 工具集

code-style

编程与开发

查看项目

更新于 10-16 04:02

技能介绍

Code Style 是一个面向已有代码库的编码规范技能,核心是四条按优先级排列的原则:存在(Exist)、复用(Reuse)、模仿(Mirror)、对称(Symmetry)。当两条原则冲突时,靠前的原则优先。

一、确认代码需要存在

写新代码前先确认它确实需要存在。删除或收窄优于新增。一个只有单一实现的抽象、只有一个调用方的配置点、调用方无法到达的分支、为预期需求搭建的脚手架,都属于可以丢弃的工作。删除已有代码前,应先追踪其调用方,确认没有依赖该行为。新增测试同样需要证明其价值:在添加之前,说明它保护的行为,以及会使它失败的可信回归场景,并确认没有现有测试已在该回归上失败。若现有测试覆盖同一契约,应扩展其用例。测试应通过生产代码已有的边界驱动,而不是新增只有测试调用的导出、标志或钩子。但输入校验、防止数据丢失的错误处理、安全控制、无障碍支持以及明确请求的内容,优先级高于本规则。

二、复用现有代码

写新辅助函数前,先检查现有方法是否可以复用或泛化。如果确实需要新辅助函数,应参照其最接近的同类进行建模。

三、复用现有模式

找到最接近的类似功能并复刻其结构,包括方法拆分、控制流、注解、守卫子句。当现有模式适用时,采用它而不是引入新模式。如果遵循现有模式会导致明显更多的代码或间接层,可以采用不同方案,但应在整个改动中一致应用。

四、精确模仿周边代码

先阅读附近代码,然后匹配括号风格、注释风格、命名约定、空行间距、代码密度和细节程度。

五、保持对称

如果新增 fooB() 与 fooA() 平行,应匹配命名、参数顺序和结构。对称性覆盖新增同类所涉及的所有命名:标识符、路由路径、配置键、事件名、环境变量、CLI 标志和文件命名方案。默认应重命名既有名称;仅当它是无法更新消费者的已发布契约,或无法与重命名同步更新时才保留原样。部署和注册视为本次改动应承担的成本:更新所有引用或注册该名称的位置属于改动的一部分。

六、逻辑顺序

新增方法、switch 分支和字段应放在镜像现有分组或业务生命周期的位置,而不是追加在末尾。

七、默认不写注释

通过命名、抽取和结构让代码自解释。想写注释时,先尝试重构使其变得不必要。仅在存在代码无法表达的承重约束时才添加,例如隐藏不变式、变通方案或非显而易见的性能特征。存疑时省略。

适用场景:在既有代码库中编写新代码、添加新功能、扩展现有测试时。限制:该技能描述的是编码原则,未提供具体的平台支持、收费信息、价格或安装步骤。