SuperAPI AI 工具集

readable-code

通用与其它

查看项目

更新于 10-16 01:19

技能介绍

用途:readable-code 是一套代码可读性审查技能,用于命名或重命名、代码深层嵌套或呈箭头形、注释只是复述代码、以及审查 diff 时触发,围绕命名、嵌套、注释三条规则展开。

主要能力: 命名:名称长度随作用域缩放,且不得说谎。三行循环里的 i 可以接受,导出名称需独立承载完整含义。名为 get_user() 却创建用户比模糊命名更糟,因为读者会信任它。留意缩写、泛化、误导性标识符,Utils、Manager、Data、Base、编号变体、近似孪生名称,缺失单位的数字,以及被否定的布尔值。 嵌套:每层缩进是读者需额外视为成立的一个条件,成本是复利而非相加——四个守卫子句成本为 4,相同逻辑嵌套则成本为 10,三层是软上限。留意箭头形 if/for/try、深层缩进的正常路径、对每次单独调用包 try/catch、在多个分支间选择的嵌套 if/else 链。 注释:与代码处于同一抽象层级的注释只是重复代码,应先重构到代码自身能表达,再删除注释。更精确(单位、边界、不变量)或更抽象(意图、契约、理由)的注释承载代码无法表达的内容,应保留。留意复述下一行的注释、解码条件或魔法数字的注释、缺少调用方级摘要的公开函数。

三者的交汇:提取代码块需要能给它命名,命名不出的块还不是一个内聚单元,应先用守卫子句扁平化而非提取;精确的命名才让“做什么”的注释可删,名字不好而保留注释是修错了地方;名字起不出来是设计反馈,只能命名为 process_and_update 的函数在提示它做两件事,只能命名为 DataManager 的类在提示职责尚未确定;误导性注释应先修名再删注释,用文字纠正坏名字会两者都留下。

检查清单:该名称在最远使用点是否仍清晰;每个布尔在 if 处是否读作正向真/假断言;每个带单位的数字是否在名称或类型中带单位;名称是否恰好承诺代码所做的事,没有隐藏的创建、修改或 I/O;是否有函数超过约三层,边界情况能否改为守卫;即将变成守卫的分支是否其实是正常行为,若是则保留 if/else;提前返回是否跳过手工清理,应优先使用语言的清理惯用法;读者能否仅从代码重建该注释,能则删除(若不能先重构再删);声明是否留下单位、边界或不变量未明,此类注释保留。

适用场景:命名与重命名、代码审查 diff、整理深层嵌套逻辑、判断注释去留。

限制与关联:相关技能 less-code-same-behavior(扁平化常暴露值得合并的重复分支,缺少它时仍应标注重复而非绕过)、python-google-docstrings 与 python-rest-docstrings(本技能建议保留的接口文档格式)。资料未提供安装命令、价格或平台信息。