Swift API Design Guidelines 是一套用于编写、命名和评审 Swift 声明的规范,参考来源为 swift.org 的官方 API 设计指南。其适用范围是仓库中任何公开的、或虽为内部但具有 API 形态的 Swift 声明,包括方法、函数、初始化器、属性等。
核心原则:所有规则共用同一个检验标准——读调用点,而不是读声明。名称只声明一次却被使用多次,因此一个读起来别扭但在调用点清晰的声明,胜过整洁但在调用点拗口的声明。遇到疑问时,把调用点写成英文句子来朗读。
基础要求:调用点的清晰度优先于简短。Swift 的简洁应来自类型系统与类型推断,而不是削减读者需要的信息。每个公开声明都应配有文档注释;如果摘要难以用一个句子片段写清楚,通常说明 API 形态本身有问题,应先修正设计再修文档注释。
清晰用法:包含所有避免调用点歧义的词,例如 remove(at: position) 优于 remove(position),后者读起来像是在删除与 position 相等的元素。省略不增加信息的词,尤其是重复类型的词,例如用 remove(_ member: Element) 而非 removeElement(_ member: Element)。参数、变量和关联类型应依据角色而非类型命名,例如 restock(from widgetFactory:) 而非 restock(from factory:)。
流畅用法:倾向让调用点读起来像合乎语法的英文短语,例如 x.insert(y, at: z)。在最初的几个参数之后,若参数不再处于调用意义的核心,流畅度可以适当降低,例如尾部的 options: 或 completionHandler:。工厂方法以 make 开头,如 x.makeIterator()。初始化器或工厂方法的第一个参数不与基名构成短语,不必强求语法连贯,例如 Color(red:green:blue:) 是好的,而 Color(havingRGBValuesRed:...) 则不好。布尔方法和属性应读作对接收者的断言,如 x.isEmpty、line1.intersects(line2)。可变/不可变方法对遵循动词/-ed 或 -ing 模式,无自然分词时使用 form- 前缀,如 sort()/sorted()、append(y)/appending(y)、formUnion(y)/union(y)。描述事物是什么的协议用名词命名(如 Collection),描述能力的协议用 -able/-ible/-ing(如 Equatable、ProgressReporting)。
术语使用:当普通词和术语都能表达含义时,优先用普通词。若使用术语,必须严格按该领域既有含义使用,不得为已有术语发明新含义。避免缩写,尤其是非标准缩写。拥抱先例:复用标准库与 Apple 框架已建立的名称和模式(如 Sequence、map、flatMap),不要另创平行词汇。
通用约定:任何非 O(1) 的计算属性都应记录复杂度,因为调用者默认属性访问是免费的。优先使用方法与属性而非自由函数;自由函数仅用于没有明显 self 的情况(如 min(x, y))、无约束泛型(如 print(x))或已确立的数学记号(如 sin(x))。命名大小写:类型与协议用大驼峰,其余用小驼峰;约定俗成全大写的缩写整体保持全大写(如 utf8Bytes、userSMTPServer),其他缩写按普通词处理(如 radarDetector)。
参数与参数标签:参数名应按照生成文档中的读法选择,而不只是调用点,例如 filter(_ predicate:) 文档读作“满足 predicate 的元素”,而 filter(_ includedInResult:) 则不然。当某个值压倒性地常见时,给参数默认值。参数标签方面:参数无法有效区分时省略全部标签,如 min(number1, number2)。保值类型转换的初始化器省略第一个标签,如 String(veryLargeNumber);收窄转换则标注,如 UInt32(truncating:)、UInt32(saturating:)。若第一个参数属于介词短语,则从介词开始标注,如 a.moveTo(x: b, y: c)、a.fadeFrom(red: b, ...)。否则,若第一个参数属于语法短语,省略其标签并把前面的词并入基名,如 x.addSubview(y);若不属于短语,则需要标签,如 view.dismiss(animated: false)。
特殊注意事项:在 API 中凡出现元组成员与闭包参数,都应为其命名,这些名字具有解释力并可在文档注释中引用,尽管闭包参数标签在调用点不可见。使用无约束多态(Any、AnyObject、无约束泛型)时需格外小心,容易产生仅在底层不同的歧义重载。
常见错误与修正:removeElement(:) 应改为 remove(:),因为方法名中的类型名与调用点重复;用 remove(x) 表示按位置删除应改为 remove(at: x),裸名词暗示按值相等删除;Color(havingRGBValuesRed:green:andBlue:) 应改为 Color(red:green:blue:);x.getIntersects(y)/x.empty 应改为 x.intersects(y)/x.isEmpty,布尔值读作断言;x.sort() 返回新数组应改为以 x.sorted() 表示非变异形式,sort() 意味着变异;能力协议命名缺少形容词后缀应改为 -able/-ible/-ing(如 ProgressReporting);本可作方法却写成自由函数(describe(x))应改为方法 x.describe(),除非没有明显的 self;缩写参数名(fn、cfg)应改为完整词(function、configuration)。
限制与未提供信息:关于该技能的收费、价格、平台支持情况、具体安装命令、官方版本号、维护者与更新记录,资料中暂未提供。