Swift 3.0 API设计准则

• 本文由CocoaChina译者自来也大人（ 博客 ）翻译，校对： hyhSuper（ github ），欢迎指正。

• 原文： API Design Guidelines

这些正在开发的API指南草案是 Swift 3.0 effort 的一部分。

全文目录

基本要素

• 使用要点要清晰

• 清晰比简洁更重要

• 写明文档注释

命名

• 命名更加明确

• 符合语法规则

• 善用专业术语

约定

• 常规约定

• 参数

特别说明

------------------------------------------------------------------------------------------------------------------------------------------------

基本要素

• 把能够清晰使用作为你设计时最重要的目标。因为代码的可读性比代码自身更重要。

• 代码的清晰逻辑性比代码的简洁性更重要。Swift代码的简洁性，不是指使用最少的字符来实现程序代码。Swift编程的简洁性带来的一个副作用是由强类型系统和减少引用文件的特性决定的。

• 使用Swift的标记语法，为每一个方法和属性写注释性文本。最理想的情况，开发者能够从注释的签名和一两句总结中明白API的使用和意义。

/// Returns the first index where `element` appears in `self`, /// or `nil` if `element` is not found. /// /// - Complexity: O(`self.count`). public func indexOf(element: Generator.Element) -> Index? {

在初步设计时，编写注释性文档是一个好的主意，因为这能使你对API设计有更深入地理解，从而有利用于API的进一步设计。

注意：设计的API应简洁可描述，否则，该API很有可能是有问题的。

命名规则

清晰表达

• 所有用来命名的单词，都应该避免使代码阅读人产生歧义。

例如，定义一个方法，该方法可以删除集合中指定位置的元素。

public mutating func removeAt(position: Index) -> Element

调用方式：

employees.removeAt(x)

如果我们省略该方法名中的单词At，就可能会让读者误认为，这个方法的作用是搜索并且删除指定元素X而不是删除集合中X位置处的元素。

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

• 省略不必要的单词。每一个被用来命名的单词都应传达精确的信息。

有时，为了命名清晰或消除歧义，可能需要使用很多的词语，但是那些读者已经明确这些表达意图的话，那么这个词语就会变得冗余，此时就应该省略掉这些冗余的词语。尤其是那些仅仅只重复类型信息的词更应被省略：

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

这个例子中，remove后Element没有使表达更清晰，因此是冗余的。如下API的表述就更好：

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

少数情况下，为了避免产生歧义，重复信息也是有必要的；但一般情况下，用一个词语而不是一个类型来描述参数的作用会更好。有关详细信息,请参阅下一项。

• 为了清晰表述参数的作用需要对弱类型信息进行补充。

特别是当参数的类型是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) rid.addObserver(self, forKeyPath: graphics) // clear

符合语法规则

• 对动态方法进行命名时，应该使用动词短语，如：

x.reverse(), x.sort(), x.append(y).

• 对静态方法进行命名时，应该使用名词短语，如：

x.distanceTo(y), i.successor().

• 当名词不能很好地表述时，使用动词来命名也是可以接受的：

let firstAndLast = fullName.split() // acceptable

当一个动态方法是用动词来表述时，那么可以用对该动词的过去时或者进行时形式（如”ed/ing”形式），来对该动态方法对应的静态方法进行命名。如：

x.sort()和x.append(y)和静态形式则为：x.sorted()和x.appending(y)。

通常情况下，一个动态方法都会有一个不同形式的静态方法，并且该静态方法的返回值与动态方法的返回值的类型相似或者相同。

对静态方法进行命名时，优先使用动词的过去时态（一般为“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()

• 对布尔类型的静态方法和属性进行命名时，应该使用断言性词语，如： x.isEmpty, line1.intersects(line2)

• 对属性描述性协议进行命名时，应该使用名词。对能力描述性协议进行命名时，应该使用带后“able”、“ible”或者“ing”等后缀的词（如：Equatable、ProgressReporting）

• 其他类型，属性，变量和常量，都应该用名词进行命名。

善用专业术语

专业术语：在特定领域或专业，有明确的，特殊含义的词或短语

• 如果常用词就能表达相同或者相近的含义，那么就不要用生涩的词语。如当“skin”能很好表达含义时，就不应用“epidermis”来表达。虽然专业术语是必不可少的交流工具，但也只能用来描述关键的含义，否则将失去其原有的含义。

• 应该遵循公认的含义：如果需要使用专业术语的话，请使用其常见的那个意思，避免产生不必要的误解。

当常用词不能准确表达其含义，或者使用常用词会导致其含义模糊不清时，才能使用专业术语。因此，应该根据所能接受的含义严格使用API专业术语。

1.不要独树一帜：以为创造出了一种新的含义，实际上只会让对这个术语了如指掌的专家感到奇怪甚至愤怒。

2.不要误导新手：每个学习此新术语的人，都会到网上查询术语的意思，以便进行理解，他们肯能看到的是其传统意思。

• 避免缩写：不标准的缩写会对这个术语造成很大的影响，因为对该缩写有效的理解取决于其对应的完整形式。

使用的任何缩写都应该是能在网上搜到其含义的

• 维持原意：不要为了让初学者更好理解，对专业述语进行优化而使其失去原有含义。

在连续数据结构进行命名时，虽然初学者可能更容易理解List，但使用Array比使用List要好。因为数组是现代计算的基础，所以每个程序员都知道或者将会知道array代表什么。使用大部分程序员都熟知的术语，这样也便于他们在网络进行查询和提问时能够更快得到反馈。

在某些特地编程领域里面，例如数学运算，一个广泛的先例术语：sin(x),显然比下面解释其含义的描述语句更好：

verticalPositionOnUnitCircleAtOriginOfEndOfRadiusWithAngle(x)

注意,在这种情况下，相比专业述语，先例词更应该谨慎缩写：虽然完整的单词是“sine”，但几十年来，编程人员一直用的都是“sin(x)”，而数学家们甚至使用了好几个世纪。

约定

常规约定

• 文档的任何计算属性复杂度不能为O(1), 人们经常假设属性访问不涉及明显的计算，因为这些属性是以抽象模型形式存诸起来的。但当这种假设不成立时, 务必要提醒他们注意。

• 优先使用方法或属性函数，而不是自由函数（free functions），因为自由函数仅在一些特殊情况才能使用：

1.没有明显的self关键字：

min(x, y, z)

2.函数为一个通用的泛型：

print(x)

3.函数的语法是已存在域符号的一部分：

sin(x)

• 遵循范例约定：类型，协议和枚举都是UpperCamelCase（大驼峰命名规则）。其他的都是按照lowerCamelCase（小驼峰命名规则）。

• 当方法都是表达相同基本含义时，它们可以共用一个基本名称，但是他们的运算必须是不同类型，或者作用在不同的域里面。

例如，下面这种表述是正确的，因为方法在本质上都是处理相同的事情：

extension Shape {   /// Returns `true` iff `other` is within the area of `self`.   func contains(other: Point) -> Bool { ... }      /// Returns `true` iff `other` is entirely within the area of `self`.   func contains(other: Shape) -> Bool { ... }      /// Returns `true` iff `other` is within the area of `self`.   func contains(other: LineSegment) -> Bool { ... } }

这是因为几何类型和集合类型是处于不同的域里面，在同一个程序里面，这样表述也是没有问题的：

extension Collection where Element : Equatable {   /// Returns `true` iff `self` contains an element equal to   /// `sought`.   func contains(sought: Element) -> Bool { ... } }

但是，下面的这些index方法具有不同的语义，就必须要使用不同的名称来命名：

extension Database {   /// Rebuilds the database's search index   func index() { ... }      /// Returns the `n`th row in the given table.   func index(n: Int, inTable: TableID) -> TableRow { ... } }

最后，不要使用返回值类型重载函数，这样使用会导致Swift在类型推到的时候，产生歧义:

extension Box {   /// Returns the `Int` stored in `self`, if any, and   /// `nil` otherwise.   func value() -> Int? { ... }      /// Returns the `String` stored in `self`, if any, and   /// `nil` otherwise.   func value() -> String? { ... } }

参数

• 当简化共用时，要充分利用默认参数。任何一个只有单一常用值的参数都可以默认参数。

默认参数通过隐藏一些不相关信息来提高可读性。例如：

let order = lastName.compare(   royalFamilyName, options: [], range: nil, locale: nil)

更简单的写法：

let order = lastName.compare(royalFamilyName)

默认参数通常优于方法簇，因为默认参数的使用为学习API的人减少认知上的负担。

extension String {   /// *...description...*   public func compare(      other: String, options: CompareOptions = [],      range: Range? = nil, locale: Locale? = nil   ) -> Ordering }

上面这种表述可能有点复杂，但是它比下面更简洁明了：

extension String {   /// *...description 1...*   public func compare(other: String) -> Ordering   /// *...description 2...*   public func compare(other: String, options: CompareOptions) -> Ordering   /// *...description 3...*   public func compare(      other: String, options: CompareOptions, range: Range) -> Ordering   /// *...description 4...*   public func compare(      other: String, options: StringCompareOptions,      range: Range, locale: Locale) -> Ordering }

方法簇中每一个成员，都需要用户单独编写和理解。如果使用它们，用户需要去了解每一个方法，有时候还要理清楚它们之间的关联。例如，fooWithBar(nil)和foo()方法并不总是同义的---从一个几乎完全相同的定义中去寻找它们之间细微的差别，是一个很繁琐的过程。从很多优秀编程人员的经验得知，应该使用一个带有默认参数的单一方法，而不是方法簇。

• 最好将带有默认值的参数放在参数列表的末尾。不带默认值的参数对于方法本身来说更重要，当被调用时提供一个稳定的初始化模式。

• 优先使用Swift语言默认外部参数标签。

换言之：

1.方法或者函数的第一个参数不需要参数标签

2.方法或者函数的其他参数都必须要参数标签

3.所有参数的初始化模块也需要参数标签

对应上面所说，如果每个参数都是像下面这种定义方式，那么所有参数也需要参数标签：

identifier: Type

只有少数几个例外情况：

1.对于无损“full-width”(即占用空间小的类型向占用空间大的类型转换)类型转换的构造器方法而言，第一个参数应该是待转换的类型，并且这个参数不应该写有外部参数标签。

extension String {   // Convert `x` into its textual representation in the given radix   init(_ x: BigInt, radix: Int = 10) // Note the initial separate underscore }  text = "The value is: " text += String(veryLargeNumber) text += " and in hexadecimal, it's" text += String(veryLargeNumber, radix: 16)

对于有损“narrowing”（即占用空间大的类型向占用空间小的类型转换）类型转换，推荐使用外部参数标签来描述这个特定类型:

extension UInt32 {   init(_ value: Int16)            // widening, so no label   init(truncating bits: UInt64)   init(saturating value: UInt64) }

3.当所有的参数都是相同的类型，不能有效区分的时候，也不应该使用参数标签。例如几个常见的例子： min(number1,number2)、zip(sequence1,sequence2)。

4.当第一个参数不可用时，这时候需要一个明显的参数标签。

extension Document {   func close(completionHandler completion: ((Bool) -> Void)? = nil) } doc1.close() doc2.close(completionHandler: app.quit)

正如你所看到的上面这个例子，方法可以都正确调用，不管参数是否被显式的传入。如果我们将参数的描述缺省，调用的时候可能有错误暗示：参数是语句的直接宾语：

extension Document {   func close(completion: ((Bool) -> Void)? = nil) } doc.close(app.quit) // Closing the quit function?

如果你把参数的描述加到函数名上面，当函数默认被调用时，可能就会产生歧义:

extension Document {   func closeWithCompletionHandler(completion: ((Bool) -> Void)? = nil) } doc.closeWithCompletionHandler()   // What completion handler?

特别说明

在重载集合中，需要特别注意无约束多态类型（如Any、AnyObjecty以及无约束泛型参数）来避免歧义。

例如，我们看下面这个重载：

struct Array {   /// Inserts `newElement` at `self.endIndex`.   public mutating func append(newElement: Element)      /// Inserts the contents of `newElements`, in order, at   /// `self.endIndex`.   public mutating func append<     S : SequenceType where S.Generator.Element == Element   >(newElements: S) }

这些方法构成了一个语义族，在第一个方法中参数类型有很大的不同，然而当Element为Any类型时，一个单个元素拥有和一系列元素相同的类型：

var values: [Any] = [1, "a"] values.append([2, 3, 4]) // [1, "a", [2, 3, 4]] or [1, "a", 2, 3, 4]?

想要去除歧义，第二个重载方法名应该更加明确：

struct Array {   /// Inserts `newElement` at `self.endIndex`.   public mutating func append(newElement: Element)      /// Inserts the contents of `newElements`, in order, at   /// `self.endIndex`.   public mutating func appendContentsOf<     S : SequenceType where S.Generator.Element == Element   >(newElements: S) }

注意，这个新方法的名称能更好的匹配文档的注释。在这个例子中，编写文档的注释实际上可以让编写API的设计者更多关注于问题的本质。

• 使用更加友好的文档注释工具。在些工具可以自动帮我们提取、生成格式化的公共文档（API参考文档），这些文档会出现在Xcode，生成的接口(interfaces)，快速帮助文档和代码补全提示中。

我们使用的Markdown编辑器能够便捷的给我们生成一个如下整齐的列表：

• -Attention: -Important: -Requires:

• -Author: -Invariant: -See:

• -Authors: -Note: -Since:

• -Bug: -Postcondition: -Throws:

• -Complexity: -Precondition: -TODO:

• -Copyright: -Remark: -Version:

• -Date: -Remarks: -Warning:

• -Experiment: -Returns:

编写一篇很棒的总结，相对来说比使用关键字，更为重要。

如果方法的签名和方法头注释行，已经描述了参数或者返回值类型信息，那么你没有必要去为它们编写一个注释性的文档来描述它们的用法或作用，如下：

/// Append `newContent` to this stream. mutating func write(newContent: String)

• 本文仅用于学习和交流目的，转载请注明文章译者、出处和本文链接。

• 感谢 博文视点 对本期活动的支持