Swift API 设计指南（上）

本文翻译自苹果官方文档：Swift API Design Guidelines，如有错漏，欢迎指出。

基本准则

• 在调用处表意足够明确是你最重要的目的。像方法和属性这样的实体（Entities）只声明一次，但却会被重复调用，所以你需要设计好你的 API 让它们可以被明确和简洁的调用。当我们评价某个设计的时候，往往需要查看它的使用场景以确保它在实际环境中足够明确，而不仅仅是看一眼它的声明。

• ** 明确比简洁更重要。**虽然 Swift 代码可以写得非常简洁，但是通过减少字符数使得代码尽可能简短却从不是我们的目标。在 Swift 中，简洁只是强类型系统和其它可以减少样板代码的特性所带来的一个副作用（side-effect）。

• 为每个声明编写文档注释。写文档时的感悟会对你的设计产生重大影响，所以不要搁置它。

命名

促使能被明确调用

• 包含所有需要的单词，以避免人们在阅读调用处的代码时感到困惑。
  譬如，有一个方法，要在集合（collection）中移除指定位置的元素。
  推荐：

extension List {
    public mutating func remove(at position: Index) -> Element
}
employees.remove(at: x)

如果我们删掉方法签名中的at，那就给人一种该方法是搜索并删除集合中等于x 的元素的感觉，而不是用x来指示元素在集合中的位置，并把该位置的元素删除。
不推荐:

employees.remove(x) // unclear: are we removing x?

• 删除不需要的单词。名字中的每个单词都应该在调用处传达出重点信息。
  更多的单词或许能澄清意图和消除歧义，但是那些读者已经知道的冗余信息都可以删掉，尤其是那些仅仅重复了类型信息的单词。
  不推荐:

public mutating func removeElement(member: Element) -> Element?
allViews.removeElement(cancelButton)

上述情况下，Element在调用处没有提供任何要点信息，如下 API 会更好。
推荐：

public mutating func remove(member: Element) -> Element?
allViews.remove(cancelButton) // clearer

个别情况下，重复类型信息对于消除歧义是必要的，但一般来说，用一个表明参数角色（role）而不是类型的词，会更好一些。详情请参看下一条。
基于变量、参数、关联类型的角色来对它们进行命名，而不是基于它们的类型。
不推荐：

var string = "Hello"
protocol ViewController {
    associatedtype ViewType : View
}
class ProductionLine {
    func restock(from widgetFactory: WidgetFactory)
}

像这样重申一遍类型名并不能最大程度提升明确性和表现力。相反，我们应该尽量选用那些表明实体角色的名字。
推荐：

var greeting = "Hello"
protocol ViewController {
    associatedtype ContentView : View
}
class ProductionLine {
    func restock(from supplier: WidgetFactory)
}

如果某个关联类型和它的协议联系非常紧密，以至于它的协议名就是它的角色名，那就给关联类型的名字加上Type避免冲突：

protocol Sequence {
    associatedtype IteratorType : Iterator
}

• 为弱类型信息的参数添加补充信息以表明参数的角色
  当参数类型是NSObject、Any、 AnyObject或者像Int、String这样的基本类型的时候，调用处的类型信息和上下文环境可能不能完全表明函数的意图。如下这个例子，它的声明可能是明确的，但在调用的地方就显得意图不明了。
  不推荐：

func add(observer: NSObject, for keyPath: String)
grid.add(self, for: graphics) // vague

为了恢复明确性，在每个弱类型参数前加一个名词用来描述它的角色。
推荐：

func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // clear

为能被流畅调用而努力

• 尽量使方法或函数名在调用的时候符合英语语法规范。
  推荐：

x.insert(y, at: z)          “x, insert y at z”
x.subViews(havingColor: y)  “x's subviews having color y”
x.capitalizingNouns()       “x, capitalizing nouns”

不推荐：

x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()

为了流畅性，可以把调用时非重点的参数放到第一或者第二个参数之后。

AudioUnit.instantiate(
    with: description, 
    options: [.inProcess], completionHandler: stopProgressBar)

• 工厂方法的命名以make开头，譬如：x.makeIterator()。

• 构造方法和工厂方法在调用时应该从一个不包含 first argument（译者注：翻译成第一个参数在这里好像不对头，索性就不翻了，大家根据下面的例子应该可以理解它的意思）的短语开始，譬如：x.makeWidget(cogCount: 47)。
  举个例子，如下这些调用的短语都不包含 first argument。
  推荐：

let foreground = Color(red: 32, green: 64, blue: 128)
let newPart = factory.makeWidget(gears: 42, spindles: 14)

而下面这段代码的 API 作者企图用 first argument 创建符合英语语法的顺畅 API：
不推荐：

let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)

事实上，本指南包含了参数标签（argument labels，译者注：应该和外部参数名一个意思吧）这样的的主题，意味着第一个参数都应该包含一个标签，除非该方法完全只是用来做类型转换的。
推荐:

let rgbForeground = RGBColor(cmykForeground)

• 基于函数和方法的副作用对它们命名
  • 没有副作用的方法读起来应该是一个名词词组，譬如：x.distance(to: y), i.successor()。
  • 有副作用的方法读起来应该是一个命令式的动词短语，譬如：print(x), x.sort(), x.append(y)。
  • 使用 “ed/ing” 规则对一个可变方法（mutating method）的不可变版本命名。
    一般来说，可变方法都会有一个对应的不可变版本，该方法会返回一个和接受值相同或者相似类型的值。
    • 倾向于用过去分词对不可变版本命名（一般是加 “ed”）：

/// Reverses `self` in-place.
mutating func reverse()
/// Returns a reversed copy of `self`.
func reversed() -> Self
...
x.reverse()
let y = x.reversed()

- 当动词后面跟了个名词的时候，用过去分词就不符合语法规范了，这时候可以用动词的现在分词对不可变版本命名，也就是加上 “ing”：

/// Strips all the newlines from \`self\`
mutating func stripNewlines()
/// Returns a copy of \`self\` with all the newlines stripped.
func strippingNewlines() -> String
...
s.stripNewlines()
let oneLine = t.strippingNewlines()

• 调用返回值为布尔型的不可变方法和属性的时候读起来应该是调用者的断言（assertions），譬如：x.isEmpty, line1.intersects(line2)。

• 用来描述是什么的协议读起来应该是个名词。**(譬如：Collection)。

• 用来描述能做什么的协议应该加上 able、ible 或者 ing 进行命名**（譬如：Equatable, ProgressReporting）。

• 其它类型、属性、变量和约束的命名都应该用名词。

待续