swift-api-design-guidelines-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swift API Design Guidelines Skill

Swift API设计指南技能

Overview

概述

Use this skill to design and review Swift APIs that are clear at the point of use, fluent in call sites, and aligned with established Swift naming and labeling conventions. Prioritize readability, explicit intent, and consistency across declarations, call sites, and documentation comments.

使用本技能可设计和评审Swift API，确保其在使用时清晰易懂、调用语法流畅，且符合既定的Swift命名与标签约定。优先保证可读性、明确的意图，以及声明、调用点和文档注释之间的一致性。

Work Decision Tree

工作决策树

1) Review existing code

1) 评审现有代码

Inspect declarations and call sites together, not declarations alone.

Check naming clarity and fluency (see

references/promote-clear-usage.md

references/strive-for-fluent-usage.md

Check argument labels and parameter naming (see

references/parameters.md

references/argument-labels.md

Check documentation comments and symbol markup (see
```
references/fundamentals.md
```
).

Check conventions and overload safety (see

references/general-conventions.md

references/special-instructions.md

同时检查声明和调用点，而非仅查看声明。

检查命名的清晰度与流畅性（参见

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) Improve existing code

2) 改进现有代码

Rename APIs that are ambiguous, redundant, or role-unclear.
Refactor labels to improve grammatical call-site reading.
Replace weakly named parameters with role-based names.
Resolve overload sets that become ambiguous with weak typing.
Strengthen documentation summaries to describe behavior and returns precisely.

重命名模糊、冗余或角色不明确的API。
重构标签以提升调用点的语法可读性。
用基于角色的名称替换命名较弱的参数。
解决因弱类型导致的重载集合歧义问题。
强化文档摘要，精准描述行为和返回值。

3) Implement new feature

3) 实现新功能

Start from use-site examples before finalizing declarations.
Choose base names and labels so calls read as clear English phrases.
Add defaults only when they simplify common usage.
Define mutating/nonmutating pairs with consistent naming.
Add concise documentation comments for every new declaration.

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

Core Guidelines

核心指南

Fundamentals

基本原则

Clarity at the point of use is the top priority.
Clarity is more important than brevity.
Every declaration should have a documentation comment.
Summaries should state what the declaration does, returns, accesses, creates, or is.
Use recognized Swift symbol markup (
```
Parameter
```
,
```
Returns
```
,
```
Throws
```
,
```
Note
```
, etc.).

使用时的清晰度是首要优先级。
清晰度比简洁性更重要。
每个声明都应有文档注释。
摘要应说明该声明的功能、返回值、访问内容、创建对象或自身定义。
使用标准的Swift符号标记（
```
Parameter
```
、
```
Returns
```
、
```
Throws
```
、
```
Note
```
等）。

Promote Clear Usage

提升使用清晰度

Include all words needed to avoid ambiguity.
Omit needless words, especially type repetition.
Name parameters and associated types by role, not type.
Add role nouns when type information is weak (
```
Any
```
,
```
NSObject
```
,
```
String
```
,
```
Int
```
).

包含所有必要的词汇以避免歧义。
省略不必要的词汇，尤其是类型重复的部分。
按角色而非类型来命名参数和关联类型。
当类型信息较弱时（如
```
Any
```
、
```
NSObject
```
、
```
String
```
、
```
Int
```
），添加角色名词。

Strive For Fluent Usage

追求调用流畅性

Prefer method names that produce grammatical, readable call sites.
Start factory methods with
```
make
```
.
Name side-effect-free APIs as noun phrases; side-effecting APIs as imperative verbs.
Keep mutating/nonmutating naming pairs consistent (
```
sort
```
/
```
sorted
```
,
```
formUnion
```
/
```
union
```
).
Boolean APIs should read as assertions (
```
isEmpty
```
,
```
intersects
```
).

优先选择能使调用点语法通顺、可读性强的方法名。
工厂方法以
```
make
```
开头。
无副作用的API命名为名词短语；有副作用的API命名为祈使动词。
保持可变/不可变方法对的命名一致性（如
```
sort
```
/
```
sorted
```
、
```
formUnion
```
/
```
union
```
）。
布尔类型API应读起来像断言（如
```
isEmpty
```
、
```
intersects
```
）。

Use Terminology Well

合理使用术语

Prefer common words unless terms of art are necessary for precision.
If using a term of art, preserve its established meaning.
Avoid non-standard abbreviations.
Embrace established domain precedent when it improves shared understanding.

除非专业术语对精准性有必要，否则优先使用常用词汇。
若使用专业术语，需保留其既定含义。
避免非标准缩写。
当领域惯例有助于提升共识时，遵循既定的领域先例。

Conventions, Parameters, And Labels

约定、参数与标签

Document complexity for computed properties that are not
```
O(1)
```
.
Prefer methods/properties to free functions except special cases.
Follow Swift casing conventions, including acronym handling.
Use parameter names that improve generated documentation readability.
Prefer default arguments over method families when semantics are shared.
Place defaulted parameters near the end.
Apply argument labels based on grammar and meaning, not style preference.

对于时间复杂度非
```
O(1)
```
的计算型属性，需记录其复杂度。
除特殊情况外，优先使用方法/属性而非自由函数。
遵循Swift的大小写约定，包括首字母缩写的处理方式。
使用能提升生成文档可读性的参数名。
当语义一致时，优先使用默认参数而非方法族。
将带默认值的参数放在参数列表末尾。
根据语法和含义应用参数标签，而非仅凭风格偏好。

Special Instructions

特殊说明

Label tuple members and name closure parameters in public API surfaces.
Be explicit with unconstrained polymorphism to avoid overload ambiguity.
Align names with semantics shown in documentation comments.

在公共API表面中，为元组成员添加标签并为闭包参数命名。
对于无约束的多态，需明确声明以避免重载歧义。
确保名称与文档注释中描述的语义一致。

Quick Reference

快速参考

Name Shape

命名格式

Situation	Preferred Pattern
Mutating verb	`reverse()`
Nonmutating verb	`reversed()` / `strippingNewlines()`
Nonmutating noun op	`union(_:)`
Mutating noun op	`formUnion(_:)`
Factory method	`makeWidget(...)`
Boolean query	`isEmpty` , `intersects(_:)`

场景	推荐格式
可变方法动词	`reverse()`
不可变方法动词	`reversed()` / `strippingNewlines()`
不可变名词操作	`union(_:)`
可变名词操作	`formUnion(_:)`
工厂方法	`makeWidget(...)`
布尔查询	`isEmpty` , `intersects(_:)`

Argument Label Rules

参数标签规则

Situation	Rule
Distinguishable unlabeled args	Omit labels only if distinction is still clear
Value-preserving conversion init	Omit first label
First arg in prepositional phrase	Usually label from the preposition
First arg in grammatical phrase	Omit first label
Defaulted arguments	Keep labels (they may be omitted at call sites)
All other arguments	Label them

场景	规则
可区分的无标签参数	仅当仍能清晰区分时才省略标签
保留值的转换初始化方法	省略第一个标签
介词短语中的第一个参数	通常使用介词作为标签
语法短语中的第一个参数	省略第一个标签
带默认值的参数	保留标签（调用时可省略）
所有其他参数	添加标签

Documentation Rules

文档规则

Declaration Kind	Summary Should Describe
Function / method	What it does and what it returns
Subscript	What it accesses
Initializer	What it creates
Other declarations	What it is

声明类型	摘要应描述
函数/方法	功能及返回值
下标	访问的内容
初始化方法	创建的对象
其他声明	自身定义

Review Checklist

评审检查清单

Clarity And Fluency

清晰度与流畅性

Call sites are clear without reading implementation details.
Base names include all words needed to remove ambiguity.
Names are concise and avoid repeating type names.
Calls read naturally and grammatically where it matters most.

无需查看实现细节即可理解调用点的含义。
基础名称包含所有消除歧义所需的词汇。
命名简洁，避免重复类型名称。
在关键场景下，调用语句读起来自然且语法通顺。

Naming Semantics

命名语义

Side-effect-free APIs read as nouns/queries.
Side-effecting APIs read as imperative verbs.
Mutating/nonmutating pairs use consistent naming patterns.
Boolean APIs read as assertions.

无副作用的API以名词/查询形式命名。
有副作用的API以祈使动词形式命名。
可变/不可变方法对使用一致的命名模式。
布尔类型API读起来像断言。

Parameters And Labels

参数与标签

Documentation And Conventions

文档与约定

Every declaration has a useful summary comment.
Symbol markup is used where appropriate.
Non-
```
O(1)
```
computed property complexity is documented.
Case conventions and acronym casing follow Swift norms.
Overloads avoid return-type-only distinctions and weak-type ambiguities.

每个声明都有实用的摘要注释。
在合适的地方使用了符号标记。
非
```
O(1)
```
复杂度的计算型属性已记录其复杂度。
大小写约定和首字母缩写的处理符合Swift规范。
重载避免了仅靠返回值区分和弱类型导致的歧义。

References

参考资料

```
references/fundamentals.md
```
- Core principles and documentation comment rules
```
references/promote-clear-usage.md
```
- Ambiguity reduction and role-based naming
```
references/strive-for-fluent-usage.md
```
- Fluency, side effects, and mutating pairs
```
references/use-terminology-well.md
```
- Terms of art, abbreviations, and precedent
```
references/general-conventions.md
```
- Complexity docs, free function exceptions, casing, overloads
```
references/parameters.md
```
- Parameter naming and default argument strategy
```
references/argument-labels.md
```
- First-argument and general label rules
```
references/special-instructions.md
```
- Tuple/closure naming and unconstrained polymorphism

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

Philosophy

设计理念

Prefer clear use-site semantics over declaration cleverness.
Follow established Swift conventions before inventing local style rules.
Optimize for maintainability and reviewability of public API surfaces.
Keep guidance practical: apply the smallest change that improves clarity.

优先考虑使用点的语义清晰，而非声明的巧妙性。
在制定本地风格规则前，先遵循既定的Swift约定。
针对公共API表面的可维护性和可评审性进行优化。
保持指导方针的实用性：采用最小的改动来提升清晰度。