Swift代码风格指南（译）

原文链接： LinkedIn’s Official Swift Style Guide

请务必阅读Apple的API设计指南。
以下提到了这些准则的具体内容+其他评论。
本指南于2018年2月14日最后更新为Swift 4.0。

代码格式

1.1 使用四个空格进行缩进。
1.2 每行最多160个字符，这样可以避免一行过长。 (Xcode->Preferences->Text Editing->Page guide at column: 设置成160即可)
1.3 确保每个文件结尾都有空白行。
1.4 确保每行都不以空白字符作为结尾（Xcode->Preferences->Text Editing->Automatically trim trailing whitespace + Including whitespace-only lines).
1.5 左大括号不用另起一行。遵守 1TBS 风格.

class SomeClass {
    func someMethod() {
        if x == y {
            /* ... */
        } else if x == z {
            /* ... */
        } else {
            /* ... */
        }
    }

    /* ... */
}

1.6 当在写一个变量类型，一个字典里的主键，一个函数的参数，遵从一个协议，或一个父类，不用在分号前添加空格。

// 指定类型
let pirateViewController: PirateViewController
// 字典语法(注意这里是向左对齐而不是分号对齐)
let ninjaDictionary: [String: AnyObject] = [
    "fightLikeDairyFarmer": false,
    "disgusting": true
]
// 声明函数
func myFunction<t, u: someprotocol where t.relatedtype == u>(firstArgument: U, secondArgument: T) {
    /* ... */
}
// 调用函数
someFunction(someArgument: "Kitten")
// 父类
class PirateViewController: UIViewController {
    /* ... */
}
// 协议
extension PirateViewController: UITableViewDataSource {
    /* ... */
}

1.7 基本来说，要在逗号后面加空格。

1	let myArray = [1, 2, 3, 4, 5]

1.8 二元运算符(+, ==, 或 ->)的前后都需要添加空格，左小括号后面和右小括号前面不需要空格。

let myValue = 20 + (30 / 2) * 3
if 1 + 1 == 3 {
    fatalError("The universe is broken.")
}
func pancake(with syrup: Syrup) -> Pancake {
    /* ... */
}

1.9 遵守Xcode内置的缩进格式（如果已经遵守，按下CTRL-i 组合键文件格式没有变化）。当声明的一个函数需要跨多行时，推荐使用Xcode默认的格式，以 Xcode7.3 为例。

// Xcode针对跨多行函数声明缩进
func myFunctionWithManyParameters(parameterOne: String,
                                  parameterTwo: String,
                                  parameterThree: String) {
    // Xcode会自动缩进
    print("\(parameterOne) \(parameterTwo) \(parameterThree)")
}
// Xcode针对多行 if 语句的缩进
if myFirstVariable > (mySecondVariable + myThirdVariable)
    && myFourthVariable == .SomeEnumValue {
    // Xcode会自动缩进
    print("Hello, World!")
}

1.10 当调用的函数有多个参数时，每一个参数另起一行，并比函数名多一个缩进。

someFunctionWithManyArguments(
    firstArgument: "Hello, I am a string",
    secondArgument: resultFromSomeFunction(),
    thirdArgument: someOtherLocalProperty)

1.11 当遇到需要处理的数组或字典内容较多需要多行显示时，需把 [ 和 ] 类似于方法体里的括号，方法体里的闭包也要做类似处理。

someFunctionWithABunchOfArguments(
    someStringArgument: "hello I am a string",
    someArrayArgument: [
        "dadada daaaa daaaa dadada daaaa daaaa dadada daaaa daaaa",
        "string one is crazy - what is it thinking?"
    ],
    someDictionaryArgument: [
        "dictionary key 1": "some value 1, but also some more text here",
        "dictionary key 2": "some value 2"
    ],
    someClosure: { parameter1 in
        print(parameter1)
    })

1.12 应尽量避免出现多行断言，可使用本地变量或其他策略。

// 推荐
let firstCondition = x == firstReallyReallyLongPredicateFunction()
let secondCondition = y == secondReallyReallyLongPredicateFunction()
let thirdCondition = z == thirdReallyReallyLongPredicateFunction()
if firstCondition && secondCondition && thirdCondition {
    // do something
}

// 不推荐
if x == firstReallyReallyLongPredicateFunction()
    && y == secondReallyReallyLongPredicateFunction()
    && z == thirdReallyReallyLongPredicateFunction() {
    // do something
}

命名

2.1 在Swift中不用如Objective-C式一样添加前缀 (如使用 GuybrushThreepwoode 而不是 LIGuybrushThreepwood)。
2.2 使用帕斯卡拼写法（又名大骆驼拼写法，首字母大写）为类型命名 (如 struct, enum, class, typedef, associatedtype 等)。
2.3 使用小骆驼拼写法 (首字母小写) 为函数，方法，变量，常量，参数等命名。
2.4 首字母缩略词在命名中一般来说都是全部大写，例外的情形是如果首字母缩略词是一个命名的开始部分，而这个命名需要小写字母作为开头，这种情形下首字母缩略词全部小写。

// "HTML" 是变量名的开头, 需要全部小写 "html"
let htmlBodyContent: String = "<p>Hello, World!</p>"
// 推荐使用 ID 而不是 Id
let profileID: Int = 1
// 推荐使用 URLFinder 而不是 UrlFinder
class URLFinder {
    /* ... */
}

2.5 所有与实例无关的常量应该是静态的。所有这些静态常量应放置在它们的类，结构或枚举的标记部分中。对于有许多常量的类，应该对具有相似或相同前缀，后缀和/或用例的常量进行分组。

// 推荐
class MyClassName {
    // MARK: - 常量
    static let buttonPadding: CGFloat = 20.0
    static let indianaPi = 3
    static let shared = MyClassName()
}

// 不推荐
class MyClassName {
    // 不要带 `k` 前缀
    static let kButtonPadding: CGFloat = 20.0

    // 不要使用 Constants 做为命名空间
    enum Constant {
        static let indianaPi = 3
    }
}

2.6 对于泛型和关联类型，可以使用单个大写字母，也可是遵从大骆驼命名方式并能描述泛型的单词。如果这个单词和要实现的协议或继承的父类有冲突，可以为相关类型或泛型名字添加 Type 作为后缀。

class SomeClass<Model> { /* ... */ }
protocol Modelable {
    associatedtype Model
}
protocol Sequence {
    associatedtype IteratorType: Iterator
}

2.7 命名应该具有描述性并且是明确的。

// 推荐
class RoundAnimatingButton: UIButton { /* ... */ }

// 不推荐
class CustomButton: UIButton { /* ... */ }

2.8 不要缩写，简写命名，或用单个字母命名。

// 推荐
class RoundAnimatingButton: UIButton {
    let animationDuration: NSTimeInterval

    func startAnimating() {
        let firstSubview = subviews.first
    }

}

// 不推荐
class RoundAnimating: UIButton {
    let aniDur: NSTimeInterval

    func srtAnmating() {
        let v = subviews.first
    }
}

2.9 如果原有命名不能明显表明类型，则属性命名内要包括类型信息。

// 推荐
class ConnectionTableViewCell: UITableViewCell {
    let personImageView: UIImageView
    let animationDuration: NSTimeInterval
    // 作为属性名的firstName，很明显是字符串类型，所以不用在命名里不用包含String
    let firstName: String
    // 虽然不推荐, 这里用 Controller 代替 ViewController 也可以。
    let popupController: UIViewController
    let popupViewController: UIViewController
    // 如果需要使用UIViewController的子类，如TableViewController, CollectionViewController, SplitViewController, 等，需要在命名里标名类型。
    let popupTableViewController: UITableViewController
    // 当使用outlets时, 确保命名中标注类型。
    @IBOutlet weak var submitButton: UIButton!
    @IBOutlet weak var emailTextField: UITextField!
    @IBOutlet weak var nameLabel: UILabel!
}
// 不推荐
class ConnectionTableViewCell: UITableViewCell {
    // 这个不是 UIImage, 不应该以Image 为结尾命名。
    // 建议使用 personImageView
    let personImage: UIImageView
    // 这个不是String，应该命名为 textLabel
    let text: UILabel
    // animation 不能清晰表达出时间间隔
    // 建议使用 animationDuration 或 animationTimeInterval
    let animation: NSTimeInterval
    // transition 不能清晰表达出是String
    // 建议使用 transitionText 或 transitionString
    let transition: String
    // 这个是ViewController，不是View
    let popupView: UIViewController
    // 由于不建议使用缩写，这里建议使用 ViewController替换 VC
    let popupVC: UIViewController
    // 技术上讲这个变量是 UIViewController, 但应该表达出这个变量是TableViewController
    let popupViewController: UITableViewController
    // 为了保持一致性，建议把类型放到变量的结尾，而不是开始，如submitButton
    @IBOutlet weak var btnSubmit: UIButton!
    @IBOutlet weak var buttonSubmit: UIButton!
    // 在使用outlets 时，变量名内应包含类型名。
    // 这里建议使用 firstNameLabel
    @IBOutlet weak var firstName: UILabel!
}

2.10 当给函数参数命名时，要确保函数易读且能理解每个参数的目的。
2.11 根据苹果接口设计指导文档, 如果协议描述的是协议做的事应该命名为名词(如Collection) ，如果描述的是行为，需添加后缀 able 或 ing (如Equatable 和 ProgressReporting)。如果上述两者都不能满足需求，可以添加Protocol作为后缀，例子见下面。

// 这个协议描述的是协议能做的事，应该命名为名词
protocol TableViewSectionProvider {
    func rowHeight(at row: Int) -> CGFloat
    var numberOfRows: Int { get }
    /* ... */
}

// 这个协议表达的是行为, 应该命名为 appropriately
protocol Loggable {
    func logCurrentState()
    /* ... */
}

// 假设我们有一个 `InputTextView` 类，但我们也想要一个协议。
// 要概括某些功能，它可能是合适的
// 可以添加 `Protocol` 作为后缀
protocol InputTextViewProtocol {
    func sendTrackingEvent()
    func inputText() -> String
    /* ... */
}

代码风格

3.1 常规范式
3.1.1 尽可能的多使用let，少使用var。

3.1.2 当需要遍历一个集合并变形成另一个集合时，推荐使用函数 map, filter 和 reduce。使用这些方法时一定要避免使用有异常抛出的闭包。（注：翻译不一定准确）

// 推荐
let stringOfInts = [1, 2, 3].flatMap { String($0) }
// ["1", "2", "3"]

// 不推荐
var stringOfInts: [String] = []
for integer in [1, 2, 3] {
    stringOfInts.append(String(integer))
}

// 推荐
let evenNumbers = [4, 8, 15, 16, 23, 42].filter { $0 % 2 == 0 }
// [4, 8, 16, 42]

// 不推荐
var evenNumbers: [Int] = []
for integer in [4, 8, 15, 16, 23, 42] {
    if integer % 2 == 0 {
        evenNumbers.append(integer)
    }
}

3.1.3 如果变量类型可以依靠推断得出，不建议声明变量时指明类型。

3.1.4 如果一个函数有多个返回值，推荐使用元组而不是 inout 参数，如果你见到一个元组多次，建议使用typealias ，而如果返回的元组有三个或多于三个以上的元素，建议使用结构体或类。

func pirateName() -> (firstName: String, lastName: String) {
    return ("Guybrush", "Threepwood")
}

let name = pirateName()
let firstName = name.firstName
let lastName = name.lastName

3.1.5 当使用委托和协议时，请注意避免出现循环引用，基本上是在定义属性的时候使用 weak 修饰。

3.1.6 在闭包里使用 self 的时候要注意出现循环引用，使用捕获列表可以避免这一点:

myFunctionWithEscapingClosure() { [weak self] (error) -> Void in
    // 方案 1

    self?.doSomething()

    // 方案 2

    guard let strongSelf = self else {
        return
    }

    strongSelf.doSomething()
}

3.1.7 Switch 模块中不用显式使用break。

3.1.8 断言流程控制的时候不要使用小括号。

// 推荐
if x == y {
    /* ... */
}

// 不推荐
if (x == y) {
    /* ... */
}

3.1.9 在写枚举类型的时候，尽量简写。

// 推荐
imageView.setImageWithURL(url, type: .person)

// 不推荐
imageView.setImageWithURL(url, type: AsyncImageView.Type.person)

3.1.10 在使用类方法的时候不用简写，因为类方法不如枚举类型一样，可以根据轻易地推导出上下文。

// 推荐
imageView.backgroundColor = UIColor.white

// 不推荐
imageView.backgroundColor = .white

3.1.11 非必须情况下不建议使用self修饰（调用属性或方法）。

3.1.12 在新写一个方法的时候，需要衡量这个方法是否将来会被重写，如果不是，请用 final 关键词修饰，这样阻止方法被重写。一般来说，final 方法可以优化编译速度，在合适的时候可以大胆使用它。但需要注意的是，在一个公开发布的代码库中使用 final 和本地项目中使用 final 的影响差别很大的。

3.1.13 在使用一些语句如 else，catch等紧随代码块的关键词的时候，确保代码块和关键词在同一行。下面是 if/else 和 do/catch 的例子。

if someBoolean {
    // do something
} else {
    // do something else
}

do {
    let fileContents = try readFile("filename.txt")
} catch {
    print(error)
}

3.1.14 当声明一个与类相关的函数或属性，而不是该类的一个实例的时候，推荐使用static关键字进行限定。只有当您特别需要在子类中重写该函数或属性的功能时，才使用类，不过要考虑使用协议来实现此功能。

3.1.15 如果你有一个函数不带任何参数，没有抛出异常，并且返回了对象或值，那么推荐使用一个计算属性。

3.2 访问控制修饰符
3.2.1 如果需要（访问修饰符），把访问修饰符放到第一个位置。
1
2
3
4
5
// 推荐
private static let myPrivateNumber: Int

// 不推荐
static private let myPrivateNumber: Int
3.2.2 访问修饰符不应单独另起一行，应和访问修饰符描述的对象保持在同一行。
1
2
3
4
5
6
7
8
9
10
// 推荐
open class Pirate {
/* ... */
}

// 不推荐
open
class Pirate {
/* ... */
}
3.2.3 internal 是默认的访问控制修饰符，可以省略不写。

3.2.4 当一个变量需要被单元测试访问时，需要声明为 internal 类型来使用@testable import {ModuleName}。如果一个变量实际上是private 类型，而因为单元测试需要被声明为 internal 类型，确定添加合适的注释文档来解释为什么这么做。这里添加注释推荐使用 - warning: 标记语法。
1
2
3
4
5
/**
这个变量是 pirateName
- warning: 定义为 internal 而不是 private 为了 `@testable`。
*/
let pirateName = "LeChuck"
3.2.5 推荐用 private 修饰属性，而不是 fileprivate。

3.2.6 当在 public 和 open 之间进行选择时，如果您想要在给定的模块和 public 之外的其他地方可以进行子类化，那么就选择 open。请注意，任何大于 internal 访问权限的内容都可以通过使用 @testable 导入进行测试，所以这不是使用 open 的理由。总的来说，当涉及到库时，推荐使用 open，但在代码库中的模块(比如应用程序中，可以很容易地同时更改多个模块的内容)时，稍微保守一些。
3.3 自定义操作符
不推荐使用自定义操作符，如果需要创建函数来替代。
在重写操作符之前，请慎重考虑是否有充分的理由一定要在全局范围内创建新的操作符，而不是使用其他策略。
你可以重载现有的操作符来支持新的类型(特别是 ==)，但是新定义的必须保留操作符的原来含义，比如 == 必须用来测试是否相等并返回布尔值。

3.4 Switch语句和枚举
3.4.1 在使用 Switch 语句时，如果选项是有限集合时，不要使用default，相反地，把一些不用的选项放到底部，并用 break关键字阻止其执行。

3.4.2 因为Swift 里 switch 中的选项默认是包含break的，如果不需要不用使用 break关键词。

3.4.3 case语句应和 switch语句左对齐，并在标准的default语句之上。

3.4.4 当定义的选项有关联值时，确保关联值有恰当的名称，而不只是类型。(如. 使用 case Hunger(hungerLevel: Int) 而不是 case Hunger(Int)).

enum Problem {
    case attitude
    case hair
    case hunger(hungerLevel: Int)
}

func handleProblem(problem: Problem) {
    switch problem {
    case .attitude:
        print("At least I don't have a hair problem.")
    case .hair:
        print("Your barber didn't know when to stop.")
    case .hunger(let hungerLevel):
        print("The hunger level is \(hungerLevel).")
    }
}

3.4.5 推荐尽可能使用fall through。

3.4.6 如果default 的选项不应该触发，可以抛出错误或断言类似的做法。

func handleDigit(_ digit: Int) throws {
    switch digit {
    case 0, 1, 2, 3, 4, 5, 6, 7, 8, 9:
        print("Yes, \(digit) is a digit!")
    default:
        throw Error(message: "The given number was not a digit.")
    }
}

3.5 可选类型
3.5.1 唯一使用隐式拆包可选型（implicitly unwrapped optionals）的场景是结合@IBOutlets，在其他场景使用非可选类型和常规可选类型，即使有的场景你确定有的变量使用的时候永远不会为 nil，但这样做可以保持一致性和程序更加健壮。

3.5.2 不要使用 as! 或 try!。

3.5.3 如果对于一个变量你不打算声明为可选类型，但当需要检查变量值是否为 nil，推荐用当前值和 nil 直接比较，而不推荐使用 if let 语法。
1
2
3
4
5
6
7
8
9
// 推荐写法
if someOptional != nil {
// do something
}

// 不推荐
if let _ = someOptional {
// do something
}
3.5.4 不要使用 unowned，unowned 和 weak 变量基本上等价，并且都是隐式拆包( unowned 在引用计数上有少许性能优化)，由于不推荐使用隐式拆包，也不推荐使用unowned 变量。
1
2
3
4
5
6
// 推荐写法
weak var parentViewController: UIViewController?

// 不推荐
weak var parentViewController: UIViewController!
unowned var parentViewController: UIViewController
3.5.5 当拆包取值时，使用和被拆包取值变量相同的名称。
1
2
3
guard let myValue = myValue else {
return
}
3.6 协议
在实现协议的时候，有两种方式来组织你的代码:
使用 // MARK: 注释来分割协议实现和其他代码。
使用 extension 在类/结构体已有代码外，但在同一个文件内。
请注意 extension 内的代码不能被子类重写，这也意味着测试很难进行。如果这是经常发生的情况，为了代码一致性最好统一使用第一种办法。否则使用第二种办法，其可以代码分割更清晰。
使用而第二种方法的时候，使用 // MARK: 依然可以让代码在 Xcode 可读性更强。

3.7 属性
3.7.1 对于只读属性，计算后(Computed)属性, 提供 getter 而不是 get {}。

var computedProperty: String {
    if someBool {
        return "I'm a mighty pirate!"
    }
    return "I'm selling these fine leather jackets."
}

3.7.2 对于属性相关方法 get {}, set {}, willSet, 和 didSet, 确保缩进相关代码块。
3.7.3 对于willSet/didSet 和 set 中的旧值和新值虽然可以自定义名称，但推荐使用默认标准名称 newValue/oldValue。

var storedProperty: String = "I'm selling these fine leather jackets." {
    willSet {
        print("will set to \(newValue)")
    }
    didSet {
        print("did set from \(oldValue) to \(storedProperty)")
    }
}

var computedProperty: String  {
    get {
        if someBool {
            return "I'm a mighty pirate!"
        }
        return storedProperty
    }
    set {
        storedProperty = newValue
    }
}

3.7.4 声明单例属性可以通过下面方式进行：

class PirateManager {
    static let shared = PirateManager()

    /* ... */
}

3.8 闭包
3.8.1 如果参数的类型很明显，可以在函数名里可以省略参数类型, 但明确声明类型也是允许的。代码的可读性有时候是添加详细的信息，而有时候部分重复，根据你的判断力做出选择吧，但前后要保持一致性。

// 省略类型
doSomethingWithClosure() { response in
    print(response)
}

// 明确指出类型
doSomethingWithClosure() { response: NSURLResponse in
    print(response)
}

// map 语句使用简写
[1, 2, 3].flatMap { String($0) }

3.8.2 如果闭包是变量类型，不需把变量值放在括号中，除非需要，如变量类型是可选类型(Optional?)，或当前闭包在另一个闭包内。确保闭包里的所以参数放在小括号中，这样()表示没有参数，Void表示不需要返回值。

let completionBlock: (Bool) -> Void = { (success) in
    print("Success? \(success)")
}

let completionBlock: () -> Void = {
    print("Completed!")
}

let completionBlock: (() -> Void)? = nil

3.8.3 在可能的情况下，将参数名称保持在同一行上，避免过多的水平溢出(即确保行少于160个字符)。

3.8.4 如果闭包是变量类型，不需把变量值放在括号中，除非需要，如变量类型是可选类型(Optional?)，或当前闭包在另一个闭包内。确保闭包里的所以参数放在小括号中，这样()表示没有参数，Void 表示不需要返回值。

// 尾随闭包
doSomething(1.0) { (parameter1) in
    print("Parameter 1 is \(parameter1)")
}

// 非 尾随闭包
doSomething(1.0, success: { (parameter1) in
    print("Success with \(parameter1)")
}, failure: { (parameter1) in
    print("Failure with \(parameter1)")
})

3.9 数组
3.9.1 基本上不要通过下标直接访问数组内容，如果可能使用如 .first 或 .last, 因为这些方法是非强制类型并不会崩溃。推荐尽可能使用 for item in items 而不是 for i in 0..< items.count 。

3.9.2 不要使用 += 或 + 操作符给数组添加新元素，使用性能较好的.append() 或.appendContentsOf()，如果需要声明数组基于其他的数组并保持不可变类型，使用 let myNewArray = [arr1, arr2].flatten()，而不是 let myNewArray = arr1 + arr2 。

3.10 错误处理
假设一个函数 myFunction 返回类型声明为 String，但是总有可能函数会遇到error，有一种解决方案是返回类型声明为 String?, 当遇到错误的时候返回 nil。

func readFile(named filename: String) -> String? {
    guard let file = openFile(named: filename) else {
        return nil
    }

    let fileContents = file.read()
    file.close()
    return fileContents
}

func printSomeFile() {
    let filename = "somefile.txt"
    guard let fileContents = readFile(named: filename) else {
        print("Unable to open file \(filename).")
        return
    }
    print(fileContents)
}

实际上如果预知失败的原因，我们应该使用Swift中的 try/catch 。
定义错误对象结构体如下:

struct Error: Swift.Error {
    public let file: StaticString
    public let function: StaticString
    public let line: UInt
    public let message: String

    public init(message: String, file: StaticString = #file, function: StaticString = #function, line: UInt = #line) {
        self.file = file
        self.function = function
        self.line = line
        self.message = message
    }
}

使用案例:

func readFile(named filename: String) throws -> String {
    guard let file = openFile(named: filename) else {
        throw Error(message: "Unable to open file named \(filename).")
    }

    let fileContents = file.read()
    file.close()
    return fileContents
}

func printSomeFile() {
    do {
        let fileContents = try readFile(named: filename)
        print(fileContents)
    } catch {
        print(error)
    }
}

其实项目中还是有一些场景更适合声明为可选类型，而不是错误捕捉和处理，比如在获取远端数据过程中遇到错误，nil作为返回结果是合理的，也就是声明返回可选类型比错误处理更合理。
整体上说，如果一个方法有可能失败，并且使用可选类型作为返回类型会导致错误原因湮没，不妨考虑抛出错误而不是吃掉它。

3.11 使用 guard 语句
3.11.1 总体上，我们推荐使用提前返回的策略，而不是 if 语句的嵌套。使用 guard 语句可以改善代码的可读性。

// 推荐
func eatDoughnut(at index: Int) {
    guard index >= 0 && index < doughnuts.count else {
        // 如果 index 超出允许范围，提前返回
        return
    }

    let doughnut = doughnuts[index]
    eat(doughnut)
}

// 不推荐
func eatDoughnut(at index: Int) {
    if index >= 0 && index < doughnuts.count {
        let doughnut = doughnuts[index]
        eat(doughnut)
    }
}

3.11.2 在解析可选类型时，推荐使用 guard 语句，而不是 if 语句，因为 guard 语句可以减少不必要的嵌套缩进。

// 推荐
guard let monkeyIsland = monkeyIsland else {
    return
}
bookVacation(on: monkeyIsland)
bragAboutVacation(at: monkeyIsland)

// 不推荐
if let monkeyIsland = monkeyIsland {
    bookVacation(on: monkeyIsland)
    bragAboutVacation(at: monkeyIsland)
}

// 禁止
if monkeyIsland == nil {
    return
}
bookVacation(on: monkeyIsland!)
bragAboutVacation(at: monkeyIsland!)

3.11.3 当解析可选类型需要决定在 if 语句和 guard 语句之间做选择时，最重要的判断标准是是否让代码可读性更强，实际项目中会面临更多的情景，如依赖 2 个不同的布尔值，复杂的逻辑语句会涉及多次比较等，大体上说，根据你的判断力让代码保持一致性和更强可读性，如果你不确定 if 语句和 guard 语句哪一个可读性更强，建议使用 guard 。

// if 语句更有可读性
if operationFailed {
    return
}

// guard 语句这里有更好的可读性
guard isSuccessful else {
    return
}

// 双重否定不易被理解 - 不要这么做
guard !operationFailed else {
    return
}

3.11.4 如果需要在2个状态间做出选择，建议使用 if 语句，而不是使用 guard 语句。

// 推荐写法
if isFriendly {
    print("Hello, nice to meet you!")
} else {
    print("You have the manners of a beggar.")
}

// 不推荐
guard isFriendly else {
    print("You have the manners of a beggar.")
    return
}

print("Hello, nice to meet you!")

3.11.5 你只应该在在失败情形下退出当前上下文的场景下使用 guard 语句，下面的例子可以解释 if 语句有时候比 guard 语句更合适 – 我们有两个不相关的条件，不应该相互阻塞。

if let monkeyIsland = monkeyIsland {
    bookVacation(onIsland: monkeyIsland)
}

if let woodchuck = woodchuck, canChuckWood(woodchuck) {
    woodchuck.chuckWood()
}

3.11.6 我们会经常遇到使用 guard 语句拆包多个可选值，如果所有拆包失败的错误处理都一致可以把拆包组合到一起 (如 return, break, continue, throw, 其他逃逸闭包等)。

// 组合在一起可以立即触发 return
guard let thingOne = thingOne,
    let thingTwo = thingTwo,
    let thingThree = thingThree else {
    return
}

// 使用独立的语句 因为每个场景返回不同的错误
guard let thingOne = thingOne else {
    throw Error(message: "Unwrapping thingOne failed.")
}

guard let thingTwo = thingTwo else {
    throw Error(message: "Unwrapping thingTwo failed.")
}

guard let thingThree = thingThree else {
    throw Error(message: "Unwrapping thingThree failed.")
}

3.11.7 不要把guard语句写在一行程序中。

// 推荐写法
guard let thingOne = thingOne else {
    return
}

// 不推荐
guard let thingOne = thingOne else { return }

文档/注释

4.1 文档
如果一个函数比 O(1) 复杂度高，你需要考虑为函数添加注释，因为函数签名(方法名和参数列表) 并不是那么的一目了然，这里推荐比较流行的插件 VVDocumenter. 不论出于何种原因，如果有任何奇淫巧计不易理解的代码，都需要添加注释，对于复杂的类/结构体/枚举/协议/属性都需要添加注释。所有公开的函数/类/变量/枚举/协议/属性/常数也都需要添加文档，特别是函数声明（包括名称和参数列表）不是那么清晰的时候。
写文档时，确保参照苹果文档中提及的标记语法合集。
在注释文档完成后，你应检查格式是否正确。
规则：

4.1.1 一行不要超过160个字符 (和代码长度限制雷同)。

4.1.2 即使文档注释只有一行，也要使用模块化格式 (/* /)。

4.1.3 注释模块中的空行不要使用 * 来占位。

4.1.4 确定使用新的 – parameter 格式，而不是就得 Use the new -:param: 格式，另外注意 parameter 是小写的。

class Human {
    /**
     这种方法为一个人提供某种食物。

     - parameter food: 你想要吃的食物。
     - parameter person: 应该吃食物的人。
     - returns: 如果食物被某人吃了则正确；否则错误。
    */
    func feed(_ food: Food, to person: Human) -> Bool {
        // ...
    }
}

4.1.5 如果需要给一个方法的参数/返回值/抛出异常添加注释，务必给所有的添加注释，即使会看起来有部分重复，否则注释会看起来不完整，有时候如果只有一个参数值得添加注释，可以在方法注释里重点描述。

4.1.6 对于复杂的类，请用适当的注释来描述类的用法。记住，markdown语法在Swift的注释文档中是有效的。因此，换行、列表等是可以使用的的。

/**
 ## 功能列表
 这个类提供下一下很赞的功能，如下:
 - 功能 1
 - 功能 2
 - 功能 3
 ## 例子
 这是一个代码块使用四个空格作为缩进的例子。
     let myAwesomeThing = MyAwesomeClass()
     myAwesomeThing.makeMoney()
 ## 警告
 使用的时候总注意以下几点
 1. 第一点
 2. 第二点
 3. 第三点
 */
class MyAwesomeClass {
    /* ... */
}

4.1.7 在提到代码时，使用代码标记 - `。

/**
 这可能和一个`UIViewController`有关。
 - warning: 在运行此函数之前，请确保`someValue`是`true`。
 */
func myFunction() {
    /* ... */
}

4.1.8 在写文档注释时，尽量保持简洁。

4.2 其他注释原则

4.2.1 // 后面要保留空格。
4.2.2 注释必须要另起一行。
4.2.3 使用注释 // MARK: - xoxo 时, 下面一行保留为空行。

class Pirate {

  // MARK: - 实例属性

  private let pirateName: String

  // MARK: - 初始化

  init() {

      /* ... */

  }

}