Swift编程规范

2021-04-01

正确性

努力让你的代码在没有警告的情况下编译。 这条规则决定了许多风格决策,比如使用 #selector 类型而不是字符串字面量。

命名

描述性和一致性的命名让软件更易于阅读和理解。使用 API 设计规范 中描述的 Swift 命名规范。 一些关键点包括如下:

  • 尽量让调用的地方更加简明
  • 简明性优先而不是简洁性
  • 使用驼峰命名法(而不是蛇形命名法)
  • 针对类型(和协议)使用首字母大写,其它都是首字母小写
  • 包含所有需要的单词,同时省略不必要的单词
  • 基于角色的命名,而不是类型
  • 有时候要针对弱引用类型信息进行补充
  • 尽量保持流畅的用法
  • 工厂方法以 make 开头
  • 命名方法的副作用
    • 不可变版本的动词方法要遵循后接 -ed, -ing 的规则
    • 可变版本的名词方法要遵循 formX 的规则
    • 布尔类型应该像断言一样读取
    • 描述 这是什么 的协议应该读作名词
    • 描述 一种能力 的协议应该以 -able 或者 -ible 结尾
  • 使用不会让专家惊讶或让初学者迷惑的术语
  • 通常要避免缩写
  • 使用名称的先例
  • 首选方法和属性而不是自由函数
  • 统一向上或向下包装首字母缩略词和首字母
  • 为相同含义的方法提供相同的基本名称
  • 避免返回类型的重载
  • 选择用于文档的好的参数名
  • 为闭包和元组参数设置标签
  • 利用默认参数的优势

Prose

在注释中引用方法时,含义明确是至关重要的。尽可能用最简单的形式引用方法。

  1. 写一个不带参数的方法: addTarget
  2. 写一个带参数标签的方法: addTarget(_:action:)

你可以用 Xcode 的跳转栏(ctrl + 6)来查看带有参数标签的方法。也可以通过Shift-Control-Option-Command-C 来复制带参数的方法签名到剪切板上

类前缀

Swift 的类自动被包含在模块分配的命名空间中。不应该再添加类似于 RW 的类前缀。如果不同模块的两个命名冲突,可以在类名前添加模块名来消除歧义。无论如何,仅在少数可能引起混淆的情况下指明模块名。

1
2
3
import SomeModule

let myClass = MyModule.UsefulClass()

代理

当创建自定义代理方法的时候,未命名的第一个参数应该是代理源。 ( UIKit 包含很多这样的例子。)

推荐:

1
2
func namePickerView(_ namePickerView: NamePickerView, didSelectName name: String)
func namePickerViewShouldReload(_ namePickerView: NamePickerView) -> Bool

不推荐:

1
2
func didSelectName(namePicker: NamePickerViewController, name: String)
func namePickerShouldReload() -> Bool

使用上下文推断的类型

使用上下文推断编译器书写更短更明确的代码。

推荐:

1
2
3
4
let selector = #selector(viewDidLoad)
view.backgroundColor = .red
let toView = context.view(forKey: .to)
let view = UIView(frame: .zero)

不推荐:

1
2
3
4
let selector = #selector(ViewController.viewDidLoad)
view.backgroundColor = UIColor.red
let toView = context.view(forKey: UITransitionContextViewKey.to)
let view = UIView(frame: CGRect.zero)

Generics

一般的类型参数应该是描述性的、大写驼峰法命名。当类名没有富有含义的关系或角色时,使用传统的单个大写字母来命名,例如 TUV

推荐:

1
2
3
struct Stack<Element> { ... }
func write<Target: OutputStream>(to target: inout Target)
func swap<T>(_ a: inout T, _ b: inout T)

不推荐:

1
2
3
struct Stack<T> { ... }
func write<target: OutputStream>(to target: inout target)
func swap<Thing>(_ a: inout Thing, _ b: inout Thing)

Language

使用美式英语拼写来匹配 Apple 的 API。

推荐:

1
let color = "red"

不推荐:

1
let colour = "red"

代码组织

用扩展将代码组织为功能逻辑块。每个扩展都应该添加 // MARK: -注释,以保证代码的结构清晰。

协议遵循

推荐为协议方法加一个单独的扩展,尤其是为一个模型加入协议遵循的时候。这可以让有关联的协议方法被分组在一起,也可以简化用类关联方法向这个类添加协议的指令。

推荐:

1
2
3
4
5
6
7
8
9
10
11
12
13
class MyViewController: UIViewController {
// 类填充在这
}

// MARK: - UITableViewDataSource
extension MyViewController: UITableViewDataSource {
// table view 的数据源方法
}

// MARK: - UIScrollViewDelegate
extension MyViewController: UIScrollViewDelegate {
// scroll view 的代理方法
}

不推荐:

1
2
3
class MyViewController: UIViewController, UITableViewDataSource, UIScrollViewDelegate {
// 所有方法
}

因为编译器不允许在派生类中重新声明协议遵循,所以并不总是需要复制基类的扩展组。如果派生类是一个终端类,并且只有少数方法会被覆盖,那么这个原则尤为正确。应由作者自行决定何时保留扩展组。

无用代码

无用代码(僵尸代码),包括 Xcode 模板代码和占位注释,应该被移除掉。教程或书籍中教用户使用的注释代码除外。

仅实现简单调用父类,但与教程无直接关联的方法应该被移除。这里包括任何为空的或无用的 UIApplicationDelegate 方法。

推荐:

1
2
3
override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
return Database.contacts.count
}

不推荐:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
// 任何可以重建资源的处理。
}

override func numberOfSections(in tableView: UITableView) -> Int {
// #warning 未完成的实现,返回节数。
return 1
}

override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
// #warning 未完成的实现,返回行数。
return Database.contacts.count
}

最小引用

引用最小化。举个例子,引用 Foundation 就足够的情况下不要再引用 UIKit 。已近引用UIKit的情况下,就不需要引入Foundation
推荐:

1
2
3
import UIKit
var view: UIView
var deviceModels: [String]

推荐:

1
2
import Foundation
var deviceModels: [String]

不推荐:

1
2
3
4
import UIKit
import Foundation
var view: UIView
var deviceModels: [String]

不推荐:

1
2
import UIKit
var deviceModels: [String]

空格

方法大括号和其他大括号( if / else / switch / while等)总是在和语句相同的行写左括号,而在新行写右括号。
提示:你可以通过选中一些代码(或按 ⌘A 选中全部)然后按 Control-I (或在目录中选择Editor -> Structure -> Re-Indent)的方式来重新缩进代码。一些 Xcode 模板代码会使用 4 个空格的制表符硬编码,这就是一个修正它的好方法。

推荐:

1
2
3
4
5
if user.isHappy {
// 做一件事
} else {
// 做另一件事
}

不推荐:

1
2
3
4
5
6
7
if user.isHappy
{
// 做一件事
}
else {
// 做另一件事
}
  • 方法之间应该只有一个空行,这样有助于视觉清晰和组织。方法中的空白应该按功能分隔代码,但在一个方法中有很多段意味着你应该将它们封装进不同的方法。
  • 方法开始和方法结束时不推荐留空行
  • 冒号总是在左边没有空格而右边有空格。比较特殊的是三元运算符 ? :、空字典[:] 和带有未命名参数 (_:)#selector 语法 .

推荐:

1
2
3
class TestDatabase: Database {
var data: [String: CGFloat] = ["A": 1.2, "B": 3.2]
}

不推荐:

1
2
3
class TestDatabase : Database {
var data :[String:CGFloat] = ["A" : 1.2, "B":3.2]
}
  • 长行应该在 70 个字符左右被换行(这里并非硬性限制,可自行调整)。
  • 避免在行结尾的地方附上空白。
  • 在每个文件的结尾处增加一个单独的换行符。

注释

需要的时候,用注释来解释一个特定的代码片段 为什么 做某件事。注释应保持要么是最新的,要么就被删除。

避免使用C语言风格的代码注释/*...*/, 使用两个或者三个斜杠的注释。建议使用Xcode的command+option+/组合键生成注释模块。

类和结构体

使用哪个?

请记住,结构体有值语义。对没有标识的事物应用结构体。一个包含 [a, b, c] 的数组和另一个包含 [a, b, c] 的数组是完全一样的。他们是可以完全互换的。使用第一个数组还是第二个数组都无所谓,因为他们代表着完全相同的事物。这就是为什么数组是结构体。

类有引用语义。对有标识或有具体生命周期的事物应用类。你需要将人建模为一个类,因为不同两个人对象是两个不同的事物。只是因为两个人拥有相同的名字和生日不意味着他们是同一个人。但是人的生日应该是一个结构体,因为 1950 年 3 月 3 日和任何其它的 1950 年 3 月 3 日日期对象是相同的。日期本身没有标识。

定义的举例

这是一个风格良好的类定义例子:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class Circle: Shape {
var x: Int, y: Int
var radius: Double
var diameter: Double {
get {
return radius * 2
}
set {
radius = newValue / 2
}
}

init(x: Int, y: Int, radius: Double) {
self.x = x
self.y = y
self.radius = radius
}

convenience init(x: Int, y: Int, diameter: Double) {
self.init(x: x, y: y, radius: diameter / 2)
}

override func area() -> Double {
return Double.pi * radius * radius
}
}

extension Circle: CustomStringConvertible {
var description: String {
return "center = \(centerString) area = \(area())"
}
private var centerString: String {
return "(\(x),\(y))"
}
}

上面的例子遵循了以下风格规范:

  • 用后面有空格而前面没有空格的冒号,为属性、变量、常量、参数声明和其它语句指定类型,例如:x: IntCircle: Shape
  • 如果多个变量和结构体共享一个共同的目的 / 上下文,则可以在同一行中定义。
  • 缩进 getter、setter 的定义和属性观察器。
  • 不要再添加如 internal 的默认修饰符。类似的,当重写一个方法时,不要再重复添加访问修饰符。
  • 在扩展中组织额外功能(例如打印)。
  • 隐藏非共享的实现细节,例如 centerString 在扩展中使用 private 访问控制。

Self 的使用

为了简洁,请避免使用 self 关键词,Swift 不需要用它来访问一个对象属性或调用它的方法。

仅在编译器需要时(在 @escaping 闭包或初始化函数中,消除参数与属性的歧义)才使用 self。换句话说,如果不需要 self 就能编译通过,则可以忽略它。

计算属性

为了简洁,如果一个计算属性是只读的,则可以忽略 get 子句。仅在提供了 set 子句的情况下才需要 get 子句。

推荐:

1
2
3
var diameter: Double {
return radius * 2
}

不推荐:

1
2
3
4
5
var diameter: Double {
get {
return radius * 2
}
}

Final

在教程中将类或成员标记为 final 会从主题分散注意力,而且也没必要。 尽管如此,final 的使用有时可以表明你的意图,且值得你这样做。在下面的例子中,Box 有特定的目的,且并不打算在派生类中自定义它。标记为 final 可以使它更清晰。

1
2
3
4
5
6
7
// Turn any generic type into a reference type using this Box class.
final class Box<T> {
let value: T
init(_ value: T) {
self.value = value
}
}

方法声明

在一行中保持较短的方法声明,包括左括号:

1
2
3
func reticulateSplines(spline: [Double]) -> Bool {
// 在这里写代码
}

对于签名较长的函数,则需在合适的位置换行,然后在后续的行中加一个额外的换行:

1
2
3
4
5
6
7
func reticulateSplines(
spline: [Double],
adjustmentFactor: Double,
translateConstant: Int,
comment: String) -> Bool {
// 在这里写代码
}

闭包表达式

仅在参数列表最后有个单独的闭包表达式参数时,使用尾随闭包语法。给闭包参数定义一个描述性的命名。

推荐:

1
2
3
4
5
6
7
8
9
UIView.animate(withDuration: 1.0) {
self.myView.alpha = 0
}

UIView.animate(withDuration: 1.0, animations: {
self.myView.alpha = 0
}, completion: { finished in
self.myView.removeFromSuperview()
})

不推荐:

1
2
3
4
5
6
7
8
9
UIView.animate(withDuration: 1.0, animations: {
self.myView.alpha = 0
})

UIView.animate(withDuration: 1.0, animations: {
self.myView.alpha = 0
}) { f in
self.myView.removeFromSuperview()
}

对于上下文清晰的单独表达式闭包,使用隐式返回:

1
2
3
attendeeList.sort { a, b in
a > b
}

使用尾随闭包的链式方法应该清晰且在上下文中易读。作者将自行抉择空格、换行、命名与匿名参数的使用。举例:

1
2
3
4
let value = numbers
.map {$0 * 2}
.filter {$0 > 50}
.map {$0 + 10}

类型

请尽可能多的使用 Swift 原生类型。 Swift 提供了 Objective-C 桥接,所以当你需要的时候你仍然可以使用全套方法。

推荐:

1
2
let width = 120.0                                    // Double
let widthString = (width as NSNumber).stringValue // String

不推荐:

1
2
let width: NSNumber = 120.0                          // NSNumber
let widthString: NSString = width.stringValue // NSString

Sprite Kit 代码中,使用 CGFloat 可以让你的代码避免太多转换,从而让你的代码更加简洁。

常量

使用 let关键字来定义常量,使用var 关键字来定义变量。如果变量的值不会改变,则要使用 let 来代替 var

提示: 一个比较好的技巧就是定义所有的东西都使用 let , 当编译器警告的时候再改为 var

你可以在一个类型里面去定义常量而不是在类型的实例变量中去使用类型属性。使用 static let 去声明一个类型属性作为常量。用这种方式声明类型属性比声明全局变量更推荐,因为这种方式更能和实例属性区分开。举例:

推荐:

1
2
3
4
5
enum Math {
static let e = 2.718281828459045235360287
static let root2 = 1.41421356237309504880168872
}
let hypotenuse = side * Math.root2

不推荐:

1
2
3
4
let e = 2.718281828459045235360287  // 污染全局命名空间
let root2 = 1.41421356237309504880168872

let hypotenuse = side * root2 // 什么 root2?

静态方法和可变类型属性

静态方法和类型属性跟全局函数和全局变量的工作原理类似,应当谨慎使用。当功能的作用域是一个特定类型或需要与 Objective-C 交互时,它们非常有用。

可选类型

在可接受 nil 值的情况下,使用 ? 声明变量和函数返回类型为可选类型。

! 声明的隐式解包类型,仅用于稍后在使用前初始化的实例变量,比如将在 viewDidLoad() 中创建子视图。

当访问一个可选值时,如果值仅被访问一次或在链中有许多可选项时,使用可选链:

1
self.textContainer?.textLabel?.setNeedsDisplay()

当一次性解包和执行多个操作更方便时,使用可选绑定:

1
2
3
if let textContainer = self.textContainer {
// 用 textContainer 做很多事情
}

在命名可选变量和属性时,需避免类似 optionalStringmaybeView 这样的命名,因为他们的可选性已经体现在类型声明中了。

对于可选绑定,使用原始名称,而不是使用像 unwrappedViewactualLabel 这样的名称。

推荐:

1
2
3
4
5
6
7
var subview: UIView?
var volume: Double?

// later on...
if let subview = subview, let volume = volume {
// 使用展开的 subview 和 volume 做某件事
}

不推荐:

1
2
3
4
5
6
7
8
var optionalSubview: UIView?
var volume: Double?

if let unwrappedSubview = optionalSubview {
if let realVolume = volume {
// 使用 unwrappedSubview 和 volume 做某件事
}
}

延迟初始化

在更细粒度地控制对象声明周期时考虑使用延迟初始化。 对于 UIViewController ,延迟初始化视图是非常正确的。你也可以直接调用 { }() 的闭包或调用私有工厂方法。例如:

1
2
3
4
5
6
7
8
9
lazy var locationManager: CLLocationManager = self.makeLocationManager()

private func makeLocationManager() -> CLLocationManager {
let manager = CLLocationManager()
manager.desiredAccuracy = kCLLocationAccuracyBest
manager.delegate = self
manager.requestAlwaysAuthorization()
return manager
}

类型推断

优先选择简洁紧凑的代码,让编译器为单个实例的常量或变量推断类型。类型推断也适合于小(非空)的数组和字典。需要时,请指明特定类型,如 CGFloatInt16

推荐:

1
2
3
4
let message = "Click the button"
let currentBounds = computeViewBounds()
var names = ["Mic", "Sam", "Christine"]
let maximumWidth: CGFloat = 106.5

不推荐:

1
2
3
let message: String = "Click the button"
let currentBounds: CGRect = computeViewBounds()
var names = [String]()

空数组和空字典的类型声明

为空数组和空字典使用类型声明。

推荐:

1
2
var names: [String] = []
var lookup: [String: Int] = [:]

不推荐:

1
2
var names = [String]()
var lookup = [String: Int]()

语法糖

推荐使用类型声明简短的版本,而不是完整的泛型语法。

推荐:

1
2
3
var deviceModels: [String]
var employees: [Int: String]
var faxNumber: Int?

不推荐:

1
2
3
var deviceModels: Array<String>
var employees: Dictionary<Int, String>
var faxNumber: Optional<Int>

函数 vs 方法

不附属于类或类型的自由函数应该被谨慎使用。可能的话,首选方法而不是自由函数。这有助于可读性和易领悟性。

自由函数最适用于它们与任何特定类或实例无关的情况。

推荐:

1
2
let sorted = items.mergeSorted()  // 容易领悟的
rocket.launch() // 模型的行为

不推荐:

1
2
let sorted = mergeSort(items)  // 难以领悟的
launch(&rocket)

自由函数示例:

1
2
let tuples = zip(a, b)  // 作为自由函数感到自然(对称)
let value = max(x, y, z) // 另一个感到自然的自由函数

内存管理

代码都不应该出现循环引用。分析你的对象图并用 weak 和 unowned 来防止强循环引用。或者,使用值类型( structenum )来彻底防止循环引用。

延长对象的生命周期

使用惯用语法 [weak self]guard let self = self else { return } 来延长对象的生命周期。 使用[weak self] 而不是 [unowned self]。 明确地延长生命周期优于可选解包。

推荐:

1
2
3
4
5
6
7
resource.request().onComplete { [weak self] response in
guard let self = self else {
return
}
let model = self.updateModel(response)
self.updateUI(model)
}

不推荐:

1
2
3
4
5
// might crash if self is released before response returns
resource.request().onComplete { [unowned self] response in
let model = self.updateModel(response)
self.updateUI(model)
}

不推荐:

1
2
3
4
5
// deallocate could happen between updating the model and updating UI
resource.request().onComplete { [weak self] response in
let model = self?.updateModel(response)
self?.updateUI(model)
}

访问控制

适时地使用 privatefileprivate 会使代码更加清晰,也会有助于封装。 使用private 要优于 fileprivate,只有在编译器报错时才使用fileprivate

私有属性和私有方法一定要使用private标注。

写基础库时注意 openpublic 的使用,基础库可能以后会使用cocoapods管理,如果不声明为open或者public, 集成在主工程中会导致无法访问。

将访问控制用作前置属性说明符。仅有 static 说明符或诸如 @IBAction@IBOutlet@discardableResult 的属性应该放在访问控制前面。

推荐:

1
2
3
4
5
private let message = "Great Scott!"

class TimeMachine {
private dynamic lazy var fluxCapacitor = FluxCapacitor()
}

不推荐:

1
2
3
4
5
fileprivate let message = "Great Scott!"

class TimeMachine {
lazy dynamic private var fluxCapacitor = FluxCapacitor()
}

控制流

优先选择 for 循环的 for-in 格式而不是 while-condition-increment 格式。

推荐:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
for _ in 0..<3 {
print("Hello three times")
}

for (index, person) in attendeeList.enumerated() {
print("\(person) is at position #\(index)")
}

for index in stride(from: 0, to: items.count, by: 2) {
print(index)
}

for index in (0...3).reversed() {
print(index)
}

不推荐:

1
2
3
4
5
6
7
8
9
10
11
12
var i = 0
while i < 3 {
print("Hello three times")
i += 1
}

var i = 0
while i < attendeeList.count {
let person = attendeeList[i]
print("\(person) is at position #\(i)")
i += 1
}

三目运算符

三目运算符?:仅在只有一个条件时使用,当有多个条件需要校验时,使用if语句或者重构成实例变量。通常情况下,仅在给一个变量赋值时,或者决定选用哪一个值时使用?:

推荐:

1
2
3
4
5
let value = 5
result = value != 0 ? x : y

let isHorizontal = true
result = isHorizontal ? x : y

不推荐:

1
result = a > b ? x = c > d ? c : d : y

黄金路径

当使用条件语句编码时,不要嵌套 if 语句。多个返回语句是可以的。guard 语句就是因为这个创建的。

推荐:

1
2
3
4
5
6
7
8
9
10
11
func computeFFT(context: Context?, inputData: InputData?) throws -> Frequencies {
guard let context = context else {
throw FFTError.noContext
}
guard let inputData = inputData else {
throw FFTError.noInputData
}

// use context and input to compute the frequencies
return frequencies
}

不推荐:

1
2
3
4
5
6
7
8
9
10
11
12
13
func computeFFT(context: Context?, inputData: InputData?) throws -> Frequencies {
if let context = context {
if let inputData = inputData {
// use context and input to compute the frequencies

return frequencies
} else {
throw FFTError.noInputData
}
} else {
throw FFTError.noContext
}
}

当用 guard 或 if let 解包多个可选值时,使用复合版本的解包来达到最小化的嵌套。举例:

推荐:

1
2
3
4
5
6
7
8
guard 
let number1 = number1,
let number2 = number2,
let number3 = number3
else {
fatalError("impossible")
}
// do something with numbers

不推荐:

1
2
3
4
5
6
7
8
9
10
11
12
13
if let number1 = number1 {
if let number2 = number2 {
if let number3 = number3 {
// do something with numbers
} else {
fatalError("impossible")
}
} else {
fatalError("impossible")
}
} else {
fatalError("impossible")
}

失败防护

对于用某些方法退出,防护语句是必要的。一般地,它应该是一行简洁的语句,比如: returnthrowbreakcontinuefatalError()。应该避免大的代码块。如果清理代码被用在多个退出点,则可以考虑用 defer 块来避免清理代码的重复。

分号

在 Swift 中,每条代码语句后面都不需要加分号。

推荐:

1
let swift = "not a scripting language"

不推荐:

1
let swift = "not a scripting language";

括号

条件周围的括号是不必要的,应该被忽略。

推荐:

1
2
3
if name == "Hello" {
print("World")
}

不推荐:

1
2
3
if (name == "Hello") {
print("World")
}

在大的表达式中,括号有时可以让代码读起来更清晰。

推荐:

1
let playerMark = (player == current ? "X" : "O")

多行字符串常量

当创建长文本的字符串常量时,建议使用多行字符串字面语法。第一行开始字面量语法但是不包含字符串值。

推荐:

1
2
3
4
5
6
7
let message = """
You cannot charge the flux \
capacitor with a 9V battery.
You must use a super-charger \
which costs 10 credits. You currently \
have \(credits) credits available.
"""

不推荐:

1
2
3
4
5
6
let message = """You cannot charge the flux \
capacitor with a 9V battery.
You must use a super-charger \
which costs 10 credits. You currently \
have \(credits) credits available.
"""

不推荐:

1
2
3
4
5
let message = "You cannot charge the flux " +
"capacitor with a 9V battery.\n" +
"You must use a super-charger " +
"which costs 10 credits. You currently " +
"have \(credits) credits available."