SuperAPI AI 工具集

swift-api-design-guidelines

编程与开发

查看项目

更新于 10-16 07:20

技能介绍

用途:把 Swift API Design Guidelines 应用到命名、参数标签、文档注释与调用点清晰度上。混合请求时只处理 API 设计部分,语言/类型系统问题交给 swift-language,并发交给 swift-concurrency,lint 配置交给 swiftlint。

主要能力:参数标签规则(首参构成语法短语则省略标签并并入基础名,如 addSubview(y);保值转换初始化器省略首标签,如 Int64(someUInt32);不可区分同辈参数省略全部标签,如 min(x, y);首参构成介词短语则用介词标签,如 fade(from: red);前两参构成单一抽象则把介词并入基础名,如 moveTo(x: b, y: c);其余一律加标签,如 split(maxSplits: 2))。副作用命名:有副作用用祈使动词,无副作用用描述结果的名词或形容词短语,布尔 API 用断言式名称。mutating/非 mutating 配对:动词操作用祈使式做变更、用分词做副本(sort()/sorted()、append(:)/appending(:)),优先 -ed,仅当 -ed 不合语法或描述直接宾语时才用 -ing;名词操作用名词做副本、form+名词做变更(union(:)/formUnion(:));工厂方法用 make 前缀。文档注释:每个公开声明都须有注释,摘要按声明种类描述动作、访问、创建或实体,写成单句片段并以句号结尾,可用 Parameter、Parameters、Returns、Throws、Complexity 等符号标记;非 O(1) 的计算属性必须写明复杂度。清晰与命名:清晰优先于简短,避免歧义与多余词;变量和参数按角色而非类型命名;当参数类型为 Any、AnyObject 或 Int、String 等基础类型时,用词补充角色信息。流式用法与协议:调用点应读作合乎语法的英文;初始化器首参不应延续类型名构成短语;协议若描述“是什么”用名词,描述能力用 -able、-ible 或 -ing 后缀。通用约定:类型与协议用 UpperCamelCase,其余用 lowerCamelCase,缩略词按位置统一大小写;优先方法与属性而非自由函数;优先单个带默认参数的方法而非方法族,默认参数放末尾且始终带标签;重载不要只在返回类型上不同。

使用方式:资料以规则表、正反例和检查清单组织,并引用 naming-and-clarity.md、argument-labels-and-parameters.md、side-effects-and-mutating-pairs.md、conventions-and-special-rules.md 等参考文件;按用途逐条核对即可。

限制:资料未提供安装命令、运行命令、收费、价格或平台信息;具体适用范围和集成方式暂未提供。