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)。

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

待续

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 148,637评论 1 318
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 63,443评论 1 266
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 99,164评论 0 218
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,075评论 0 188
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,080评论 1 266
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,365评论 1 184
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 30,901评论 2 283
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,649评论 0 176
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,122评论 0 223
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,734评论 2 225
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,093评论 1 236
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,548评论 2 222
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,028评论 3 216
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,765评论 0 9
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,291评论 0 178
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,162评论 2 239
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,293评论 2 242

推荐阅读更多精彩内容