swift-api-design-guidelines-skill

Swift API 设计指南技能

概述

使用此技能设计和审查 Swift API，使其在使用时清晰明了、调用点表达流畅，并符合既有的 Swift 命名和标签惯例。优先考虑可读性、明确的意图，以及声明、调用点和文档注释之间的一致性。

工作决策树

1) 审查现有代码

• 一起检查声明和调用点，而不只是检查声明。
• 检查命名的清晰度和流畅度（参见 references/promote-clear-usage.md、references/strive-for-fluent-usage.md）。
• 检查参数标签和参数命名（参见 references/parameters.md、references/argument-labels.md）。
• 检查文档注释和符号标记（参见 references/fundamentals.md）。
• 检查惯例和重载安全性（参见 references/general-conventions.md、references/special-instructions.md）。

2) 改进现有代码

• 重命名含义模糊、冗余或角色不明确的 API。
• 重构标签，让调用点读起来更符合语法习惯。
• 将命名较弱的参数替换为基于角色的名称。
• 解决因类型较弱而变得含糊的重载集合。
• 完善文档摘要，准确描述行为和返回值。

3) 实现新功能

• 在最终确定声明之前，先从使用场景示例入手。
• 选择基础名称和标签，让调用语句读起来像清晰的英文短语。
• 仅在默认值能简化常见用法时才添加默认值。
• 为可变与非可变操作定义命名一致的配对。
• 为每个新声明添加简洁的文档注释。

核心指南

基础要点

• 使用时的清晰度是首要目标。
• 清晰度比简洁更重要。
• 每个声明都应有文档注释。
• 摘要应说明声明的功能、返回值、访问内容、创建内容或所代表的对象。
• 使用 Swift 认可的符号标记（Parameter、Returns、Throws、Note 等）。

提升用法清晰度

• 补全避免歧义所需的所有词语。
• 省略不必要的词语，尤其是重复类型信息的词语。
• 根据角色而非类型为参数和关联类型命名。
• 类型信息较弱时（Any、NSObject、String、Int），添加表示角色的名词。

力求用法流畅

• 优先选择能让调用点读起来符合语法、自然流畅的方法名。
• 工厂方法以 make 开头。
• 无副作用的 API 命名为名词短语；有副作用的 API 命名为祈使动词。
• 保持可变与非可变操作配对的命名一致（sort/sorted、formUnion/union）。
• 布尔 API 应读起来像断言（isEmpty、intersects）。

正确使用术语

• 除非为确保精确性必须使用专业术语，否则优先使用常见词语。
• 使用专业术语时，保留其既定含义。
• 避免使用非标准缩写。
• 在有助于增进共同理解时，遵循既有的领域惯例。

惯例、参数和标签

• 对复杂度不是 O(1) 的计算属性，注明其复杂度。
• 除特殊情况外，优先使用方法或属性，而不是全局函数。
• 遵循 Swift 大小写惯例，包括缩略词的处理方式。
• 使用能提升生成的文档可读性的参数名称。
• 语义相同时，优先使用默认参数，而不是成组的方法。
• 将带默认值的参数放在靠后的位置。
• 根据语法和含义应用参数标签，而非个人风格偏好。

特别说明

• 为公开 API 中的元组成员添加标签，并为闭包参数命名。
• 对无约束多态明确处理，以避免重载歧义。
• 使名称与文档注释中展示的语义保持一致。

快速参考

名称形式

情况	首选模式
可变动词	reverse()
非可变动词	reversed() / strippingNewlines()
非可变名词操作	union(_:)
可变名词操作	formUnion(_:)
工厂方法	makeWidget(...)
布尔查询	isEmpty、intersects(_:)

参数标签规则

情况	规则
可区分的无标签参数	仅在仍然清晰可辨时省略标签
保留值的转换初始化器	省略第一个标签
介词短语中的第一个参数	通常根据介词确定标签
语法短语中的第一个参数	省略第一个标签
有默认值的参数	保留标签（调用时可以省略标签）
其他所有参数	添加标签

文档规则

声明类型	摘要应描述
函数 / 方法	它的功能及返回值
下标	它访问的内容
初始化器	它创建的内容
其他声明	它是什么

审查清单

清晰度与流畅度

• 无需阅读实现细节，调用处也清晰易懂。
• 基本名称包含消除歧义所需的所有词语。
• 名称简洁，避免重复类型名称。
• 在最重要的地方，调用读起来自然且符合语法。

命名语义

• 无副作用的 API 读起来像名词 / 查询。
• 有副作用的 API 读起来像祈使动词。
• 可变 / 不可变成对 API 的命名模式保持一致。
• 布尔 API 读起来像断言。

参数与标签

• 参数名称有助于文档说明和明确角色。
• 默认参数让常见用法更简单。
• 有默认值的参数靠近末尾。
• 第一个参数标签遵循语法和转换规则。
• 除非有充分理由省略，否则其余参数都应添加标签。

文档与约定

• 每个声明都有实用的摘要注释。
• 在适当之处使用符号标记。
• 记录非 O(1) 计算属性的复杂度。
• 大小写约定和缩略词大小写遵循 Swift 规范。
• 重载避免仅通过返回类型区分，以及弱类型歧义。

参考资料

• references/fundamentals.md - 核心原则和文档注释规则
• references/promote-clear-usage.md - 减少歧义和基于角色的命名
• references/strive-for-fluent-usage.md - 流畅度、副作用和可变成对 API
• references/use-terminology-well.md - 专业术语、缩略语和先例
• references/general-conventions.md - 复杂度文档、自由函数例外、大小写和重载
• references/parameters.md - 参数命名和默认参数策略
• references/argument-labels.md - 第一个参数及一般标签规则
• references/special-instructions.md - 元组 / 闭包命名和无约束多态

理念

• 优先考虑使用处语义清晰，而非声明写法巧妙。
• 优先遵循既有的 Swift 约定，而非自行制定局部风格规则。
• 以提升公共 API 表面的可维护性和可审查性为目标。
• 保持指导实用：只做能改善清晰度的最小改动。