Swift style guide.

Introduction

API Design Guidelines是蘋(píng)果專(zhuān)門(mén)針對(duì)API的一個(gè)規(guī)范，本規(guī)范涉及到一些相關(guān)的內(nèi)容，大都是保持和蘋(píng)果的規(guī)范一致。

它絕大部分內(nèi)容，集合了The Official raywenderlich.com Swift Style Guide.和GitHub's Swift Style Guide，并刪減了一些不適合編碼的規(guī)則。

同時(shí)，Swift語(yǔ)言在快速的發(fā)展中，這個(gè)規(guī)范也會(huì)隨著Swift的發(fā)展、以及對(duì)Swift更多的使用和了解，持續(xù)地進(jìn)行修改和完善。

Table of Contents

• Correctness
• Naming
  • Protocols
  • Enumerations
  • Selectors
  • Generics
  • Class Prefixes
  • Language
• Code Organization
  • Protocol Conformance
  • Unused Code
  • Minimal Imports
• Spacing
• Comments
• Classes and Structures
  • Use of Self
  • Protocol Conformance
  • Computed Properties
  • Final
• Function Declarations
• Closure Expressions
• Types
  • Constants
  • Optionals
  • Struct Initializers
  • Lazy Initialization
  • Type Inference
  • Syntactic Sugar
• Functions vs Methods
• Memory Management
• Access Control
• Control Flow
• Golden Path
  • Failing Guards
• Semicolons
• Parentheses
• Use whitespace around operator definitions
• 和Xcode集成的格式檢查工具
• Document Revision History

<h2 id="correctness"> Correctness </h2>

在Swift中把warnings當(dāng)做errors。該規(guī)則會(huì)解決掉很多其他的代碼格式化規(guī)則，比如不要使用 ++和--操作符、不要使用C類(lèi)型的for循環(huán)、不要直接使用字符串作為selector等。

<h2 id="naming"> Naming </h2>

classes, structures, enumerations 和 protocols采用首字母大寫(xiě)的駝峰命名法，method names and variables采用首字母小寫(xiě)的駝峰命名法。

Preferred:

swift
private let maximumWidgetCount = 100

class WidgetContainer {
  var widgetButton: UIButton
  let widgetHeightPercentage = 0.85
}

Not Preferred:

swift
let MAX_WIDGET_COUNT = 100

class app_widgetContainer {
  var wBut: UIButton
  let wHeightPct = 0.85
}

縮寫(xiě)應(yīng)該避免，但如URL、ID這種常見(jiàn)的縮寫(xiě)可以使用。

API Design Guidelines中提到，如果使用這些縮寫(xiě)，字母應(yīng)該全為大寫(xiě)或者小寫(xiě)。Examples:

Preferred

let urlString: URLString
let userID: UserID

Not Preferred

let uRLString: UrlString
let userId: UserId

使用argument label，替代注釋?zhuān)勾aself-documenting，可讀性更強(qiáng)。

swift
func convertPointAt(column: Int, row: Int) -> CGPoint
func timedAction(afterDelay delay: NSTimeInterval, perform action: SKAction) -> SKAction!

// would be called like this:
convertPointAt(column: 42, row: 13)
timedAction(afterDelay: 1.0, perform: someOtherAction)

<h3 id="protocols"> Protocols </h3>

按照蘋(píng)果的API Design Guidelines，Protocols名字可以使用名詞來(lái)描述這個(gè)Protocol的內(nèi)容，比如Collection, WidgetFactory。

或以-ing、-able結(jié)尾來(lái)描述Protocol實(shí)現(xiàn)的一些功能，比如: Equatable, Resizing。

<h3 id="enumerations"> Enumerations </h3>

按照蘋(píng)果的API Design Guidelines，枚舉值使用小寫(xiě)開(kāi)頭的駝峰命名法，也就是lowerCamelCase。

swift
enum Shape {
  case rectangle
  case square
  case rightTriangle
  case equilateralTriangle
}

<h3 id="class-prefixes"> Class Prefixes </h3>

在Swift里面，每一個(gè)module都是一個(gè)namesapce。而在ObjC里沒(méi)有namespace的概念，只是在每個(gè)類(lèi)名前面添加前綴，比如NSArray。

當(dāng)不同的module有同名的類(lèi)名時(shí)，需要指明module name。

swift
import SomeModule

let myClass = MyModule.UsefulClass()

<h3 id="selectors"> Selectors </h3>

Selectors是在ObjC中為許多Cocoa and Cocoa Touch APIs做處理的函數(shù)。在Swift2.2，我們可以使用類(lèi)型不安全的字符串來(lái)指定一個(gè)Selector。但在Swift3,這種方式將使Xcode報(bào)一個(gè)警告，在警告的"Fix it"按鈕里面，會(huì)使用完全類(lèi)型安全的方式去替換這個(gè)不安全的字符串。并且我們經(jīng)常能夠使用代碼所在的上下文來(lái)簡(jiǎn)化Swift3中Selector的表達(dá)式。

Preferred:

swift
let sel = #selector(viewDidLoad)

Not Preferred:

swift
let sel = #selector(ViewController.viewDidLoad)

<h3 id="generics"> Generics </h3>

范型的類(lèi)型名，應(yīng)該是描述性的名詞、以大寫(xiě)開(kāi)頭的駝峰命名。如果不能起一個(gè)有意義的關(guān)系或角色名稱(chēng)，可以使用T、U或V。

Preferred:

swift
struct Stack<Element> { ... }
func writeTo<Target: OutputStream>(inout target: Target)
func max<T: Comparable>(x: T, _ y: T) -> T

Not Preferred:

swift
struct Stack<T> { ... }
func writeTo<target: OutputStream>(inout t: target)
func max<Thing: Comparable>(x: Thing, _ y: Thing) -> Thing

<h3 id="language"> Language </h3>

為了和蘋(píng)果的API匹配，使用美式英語(yǔ)。

Preferred:

swift
let color = "red"

Not Preferred:

swift
let colour = "red"

<h2 id="code-organization"> Code Organization </h2>

多使用extension來(lái)組織代碼。每個(gè) extensions使用// MARK: -來(lái)分隔開(kāi)。

<h3 id="protocol-conformance"> Protocol Conformance </h3>

當(dāng)一個(gè)類(lèi)遵守一個(gè)協(xié)議時(shí)，使用extension來(lái)組織代碼。

Preferred:

swift
class MyViewcontroller: UIViewController {
  // class stuff here
}

// MARK: - UITableViewDataSource
extension MyViewcontroller: UITableViewDataSource {
  // table view data source methods
}

// MARK: - UIScrollViewDelegate
extension MyViewcontroller: UIScrollViewDelegate {
  // scroll view delegate methods
}

Not Preferred:

swift
class MyViewcontroller: UIViewController, UITableViewDataSource, UIScrollViewDelegate {
  // all methods
}

<h3 id="unused-code"> Unused Code </h3>

能刪除的代碼，都刪掉。

Not Preferred:

swift
override func didReceiveMemoryWarning() {
   super.didReceiveMemoryWarning()
  // Dispose of any resources that can be recreated.
}

override func numberOfSectionsInTableView(tableView: UITableView) -> Int {
   // #warning Incomplete implementation, return the number of sections
   return 1
}

override func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
  // #warning Incomplete implementation, return the number of rows
  return Database.contacts.count
}

Preferred:

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

<h3 id="minimal-imports"> Minimal Imports </h3>

盡可能減少依賴(lài)和import。比如只需要引入Foundation的時(shí)候，就不要引入U(xiǎn)IKit。

<h2 id="spacing"> Spacing </h2>

• 縮進(jìn)使用4個(gè)空格(該處只要團(tuán)隊(duì)統(tǒng)一就行):
• 方法體的花括號(hào)和其它的花括號(hào)(if/else/switch/while etc.)，需要加入一個(gè)空格后在行尾開(kāi)啟，在新一行關(guān)閉（Xcode默認(rèn)）。
• 提示：?A選中代碼后使用Control-I (或者菜單Editor\Structure\Re-Indent)來(lái)調(diào)整縮進(jìn).

Preferred:

swift
if user.isHappy {
  // Do something
} else {
  // Do something else
}

Not Preferred:

swift
if user.isHappy
{
  // Do something
}
else {
  // Do something else
}

• methods之間只留一個(gè)空行。methods內(nèi)部，使用空行來(lái)分隔不同功能的代碼，為不同的section。一個(gè)method內(nèi)部的section不宜太多，否則應(yīng)該考慮分拆成不同函數(shù)。
• 冒號(hào)左邊沒(méi)有空格，右邊有一個(gè)空格。Exception：? : 和 [:]。

Preferred:

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

Not Preferred:

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

<h2 id="comments"> Comments </h2>

盡可能避免大量使用注釋?zhuān)玫拇a應(yīng)該盡可能是self-documenting。

如果需要注釋?zhuān)挥脕?lái)解釋為什么這段代碼要這么寫(xiě)，而不是解釋代碼的邏輯。
代碼變化時(shí)也需要馬上更新注釋?zhuān)荒苡姓`導(dǎo)。如果不能及時(shí)更新就刪掉該處注釋。

Exception: 上面兩條不適用于生成文檔用的注釋.

<h2 id="classes-and-structures"> Classes and Structures </h2>

應(yīng)該使用哪一個(gè)?

記住，struct具有值語(yǔ)義。沒(méi)有id(唯一標(biāo)識(shí)符)的事物就應(yīng)該使用struct。比如一個(gè)含有[a, b, c]的數(shù)組和另一個(gè)含有[a, b, c]的數(shù)組是完全可交換的。你使用第一個(gè)數(shù)組還是第二個(gè)完全沒(méi)有關(guān)系，因?yàn)樗麄兇硗粋€(gè)事物，這也是為什么在Swift里面數(shù)組是用struct結(jié)構(gòu)來(lái)表示的。

而類(lèi)具有引用語(yǔ)義。具有id(唯一標(biāo)識(shí)符)或者具有特定生命周期的事物就應(yīng)該使用類(lèi)來(lái)表示。你將使用類(lèi)來(lái)表示人的數(shù)據(jù)結(jié)構(gòu)，因?yàn)閮蓚€(gè)人完全是不同的事物，只是因?yàn)閮蓚€(gè)人具有相同名字和生日，并不意味著這是相同的一個(gè)人。但是一個(gè)人的生日可以使用struct來(lái)表示，因?yàn)橐粋€(gè)變量中的1950年3月3號(hào)和另一個(gè)的1950年3月3號(hào)是完全相同的。日期是不具有id的。

但有些時(shí)候，一個(gè)事物應(yīng)該是struct的，但需要遵循AnyObject或者由于歷史原因被模型化為類(lèi)了(NSDate, NSSet)。除了這些異常情況，盡量遵循該條原則。

<h3 id="example-definition"> Example definition </h3>

下面是一個(gè)比較規(guī)范的Class定義：

swift
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)
  }

  func describe() -> String {
    return "I am a circle at \(centerString()) with an area of \(computeArea())"
  }

  override func computeArea() -> Double {
    return M_PI * radius * radius
  }

  private func centerString() -> String {
    return "(\(x),\(y))"
  }
}

上面的例子，給我們演示了這些規(guī)范：

• 冒號(hào)在用于指明類(lèi)型時(shí)，左邊沒(méi)有空格，右邊有一個(gè)空格。
• 當(dāng)一組變量、常量有關(guān)聯(lián)時(shí)，定義在一行里。
• 函數(shù)修飾符internal是缺省值，可以省略。重載一個(gè)函數(shù)時(shí)，訪問(wèn)修飾符也可以省略掉。

<h3 id="use-of-self"> Use of Self </h3>

避免使用self來(lái)訪問(wèn)屬性。除非需要區(qū)分函數(shù)參數(shù)和屬性。

swift
class BoardLocation {
  let row: Int, column: Int

  init(row: Int, column: Int) {
    self.row = row
    self.column = column
    
    let closure = {
      print(self.row)
    }
  }
}

<h3 id="computed-properties"> Computed Properties </h3>

Computed property一般是只讀，同時(shí)省略get clause。get clause只是當(dāng)set clause存在時(shí)才需要寫(xiě)。

Preferred:

swift
var diameter: Double {
  return radius * 2
}

Not Preferred:

swift
var diameter: Double {
  get {
    return radius * 2
  }
}

<h3 id="final"> Final </h3>

當(dāng)一個(gè)類(lèi)不想被繼承時(shí)，使用final關(guān)鍵字。Example:

swift
// 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
  }
}

<h2 id="function-declarations"> Function Declarations </h2>

在一行中保持簡(jiǎn)短的函數(shù)聲明，函數(shù)體的左方括號(hào)也需要放在這一行。

swift
func reticulateSplines(spline: [Double]) -> Bool {
  // reticulate code goes here
}

如果一個(gè)函數(shù)簽名過(guò)長(zhǎng)，則選擇合適的地方換行，并在新的一行加入足夠的縮進(jìn)。

swift
func reticulateSplines(spline: [Double], adjustmentFactor: Double,
    translateConstant: Int, comment: String) -> Bool {
  // reticulate code goes here
}

<h2 id="closure-expressions"> Closure Expressions </h2>

方法的參數(shù)列表最后一參數(shù)類(lèi)型為閉包時(shí)，可以使用尾閉包。但只在只存在一個(gè)閉包參數(shù)時(shí)才使用尾閉包。

Preferred:

swift
UIView.animateWithDuration(1.0) {
  self.myView.alpha = 0
}

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

Not Preferred:

swift
UIView.animateWithDuration(1.0, animations: {
  self.myView.alpha = 0
})

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

只有一個(gè)表達(dá)式的、用來(lái)返回值的閉包，可以省略return。

swift
attendeeList.sort { a, b in
  a > b
}

<h2 id="types"> Types </h2>

盡可能使用Swift原生類(lèi)型，而不是使用ObjC的NS類(lèi)型。

Preferred:

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

Not Preferred:

swift
let width: NSNumber = 120.0                          // NSNumber
let widthString: NSString = width.stringValue        // NSString

但是有些情況例外，比如在寫(xiě)Sprite Kit代碼時(shí)，用CGFloat可以減少轉(zhuǎn)換。

<h3 id="constants"> constants </h3>

盡可能使用let，只有在需要使用變量的時(shí)候使用var。

Tip: 有一個(gè)辦法能達(dá)到上面的目的，就是自己只寫(xiě)let，讓編譯器幫你確定哪些需要改成var。

使用static let定義類(lèi)常量，而不是實(shí)例常量，或者全局常量。

Preferred:

swift
enum Math {
  static let e  = 2.718281828459045235360287
  static let pi = 3.141592653589793238462643
}

radius * Math.pi * 2 // circumference

Note: 使用枚舉定義常量的好處是讓常量定義在特定的命名空間。

Not Preferred:

swift
let e  = 2.718281828459045235360287  // pollutes global namespace
let pi = 3.141592653589793238462643

radius * pi * 2 // is pi instance data or a global constant?

<h3 id="optionals"> Optionals </h3>

當(dāng)訪問(wèn)一個(gè)optional value前，需要訪問(wèn)多個(gè)optional value時(shí)，使用optional chaining：

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

訪問(wèn)一個(gè)optional value后，需要執(zhí)行多個(gè)操作，可以使用optional binding：

swift
if let textContainer = self.textContainer {
  // do many things with textContainer
}

給optional變量命名時(shí)，不要使用類(lèi)似optionalString或maybeView這樣的命名，因?yàn)閛ptional已經(jīng)在類(lèi)型聲明中體現(xiàn)。

相對(duì)應(yīng)的，使用unwrapped value時(shí)，避免使用unwrappedView或actualLabel這樣的命名，使用optional變量名就可以了。

Preferred:

swift
var subview: UIView?
var volume: Double?

// later on...
if let subview = subview, volume = volume {
  // do something with unwrapped subview and volume
}

Not Preferred:

swift
var optionalSubview: UIView?
var volume: Double?

if let unwrappedSubview = optionalSubview {
  if let realVolume = volume {
    // do something with unwrappedSubview and realVolume
  }
}

避免使用可選值的強(qiáng)制解析

如果你有一個(gè)變量 foo 是 FooType? 或者 FooType!類(lèi)型，如果可能，盡量不要使用強(qiáng)制解析來(lái)獲取 foo真正的值。

Preferred:

swift
if let foo = foo {
    // Use unwrapped `foo` value in here
} else {
    // If appropriate, handle the case where the optional is nil
}

或者，在一些情況下你可以使用可選鏈，例如:

swift
// Call the function if `foo` is not nil. If `foo` is nil, ignore we ever tried to make the call
foo?.callSomethingIfFooIsNotNil()

顯示的 if let可選綁定是安全的代碼范式。強(qiáng)制解析常常會(huì)引起運(yùn)行時(shí)的崩潰。

避免使用隱士強(qiáng)制解析

如果 foo可以是nil, 盡量使用 let foo: FooType?這種范式，而不要使用let foo: FooType! (一般來(lái)說(shuō)，使用!的地方都可以使用?)

顯示的可選類(lèi)型是安全的代碼范式。隱士強(qiáng)制解析有可能引起運(yùn)行時(shí)的崩潰。

<h3 id="struct-initializers"> Struct Initializers </h3>

使用Swfit原生的struct initializers，而不是遺留的CGGeometry constructors。

Preferred:

swift
let bounds = CGRect(x: 40, y: 20, width: 120, height: 80)
let centerPoint = CGPoint(x: 96, y: 42)

Not Preferred:

swift
let bounds = CGRectMake(40, 20, 120, 80)
let centerPoint = CGPointMake(96, 42)

同樣的，使用struct-scope constants CGRect.infinite， CGRect.null， etc， 而不是global constants CGRectInfinite, CGRectNull, etc。
你也可以使用.zero來(lái)給變量賦值，如var frame = CGRect.zero。對(duì)于一個(gè)已經(jīng)存在的變量也可以這樣bounds = .zero

<h3 id="lazy-initialization"> Lazy Initialization </h3>

合適的時(shí)候考慮使用lazy加載來(lái)更好的控制一個(gè)對(duì)象的生命周期。這對(duì)UIViewController懶加載view特別有用。你可以使用一個(gè)形如 { }() 的立即調(diào)用的閉包，或者調(diào)用一個(gè)private的工廠函數(shù)。例如:

swift
lazy var locationManager: CLLocationManager = self.makeLocationManager()

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

Notes:

• [unowned self] 在這里不需要，這里不會(huì)產(chǎn)生循環(huán)引用。
• 因?yàn)長(zhǎng)ocation manager會(huì)彈出彈框詢(xún)問(wèn)用戶(hù)定位的權(quán)限，所以這里控制它的生命周期很有意義。

<h3 id="type-inference"> Type Inference </h3>

盡量讓編譯器使用類(lèi)型推斷來(lái)標(biāo)示常量或者變量的類(lèi)型，這樣可以簡(jiǎn)短代碼。類(lèi)型推斷也適用于小數(shù)據(jù)量(不為空)的數(shù)組和字典。只有當(dāng)需要的時(shí)候，才指明類(lèi)型，如CGFloat or Int16。

Preferred:

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

Not Preferred:

swift
let message: String = "Click the button"
let currentBounds: CGRect = computeViewBounds()
let names = [String]()

空數(shù)組或者字典的類(lèi)型標(biāo)注

對(duì)于空的數(shù)組、字典需要顯示使用類(lèi)型標(biāo)注。對(duì)于初始化的時(shí)候使用大量、對(duì)方數(shù)組、字典常量初始化的情況也需要顯示使用類(lèi)型標(biāo)注。

Preferred:

swift
var names: [String] = []
var lookup: [String: Int] = [:]

Not Preferred:

swift
var names = [String]()
var lookup = [String: Int]()

NOTE: 準(zhǔn)守這條規(guī)則意味著取一個(gè)描述性的名稱(chēng)顯示更加重要。

<h3 id="syntactic-sugar"> Syntactic Sugar </h3>

盡可能使用語(yǔ)法糖。

Preferred:

swift
var deviceModels: [String]
var employees: [Int: String]
var faxNumber: Int?

Not Preferred:

swift
var deviceModels: Array<String>
var employees: Dictionary<Int, String>
var faxNumber: Optional<Int>

<h2 id="functions-vs-methods"> Functions vs Methods </h2>

不依附于任何class或type的函數(shù)被稱(chēng)為free function，應(yīng)該盡量避免使用，因?yàn)椴惶谜业竭@個(gè)方法。

Preferred

swift
let sorted = items.mergeSort()  // easily discoverable
rocket.launch()  // clearly acts on the model

Not Preferred

swift
let sorted = mergeSort(items)  // hard to discover
launch(&rocket)

Free Function Exceptions(下面的函數(shù)明確應(yīng)該是fress function,并且比較好理解)

swift
let tuples = zip(a, b)  // feels natural as a free function (symmetry)
let value = max(x,y,z)  // another free function that feels natural

<h2 id="memory-management"> Memory Management </h2>

代碼應(yīng)該避免參數(shù)循環(huán)引用。分析你的對(duì)象引用視圖，并使用weak 和 unowned避免不必要的強(qiáng)引用。同時(shí)可以選擇使用值類(lèi)型(struct, enum)來(lái)避免循環(huán)引用。

擴(kuò)展一個(gè)對(duì)象的生命周期

可以使用 [weak self] 和 guard let strongSelf = self else { return } 組合的方式來(lái)擴(kuò)展一個(gè)對(duì)象的生命周期。當(dāng) self 明顯生命周期比使用它的閉包更長(zhǎng)的時(shí)候，最好選擇使用 [unowned self]。

Preferred

swift
resource.request().onComplete { [weak self] response in
  guard let strongSelf = self else { 
    return 
  }
  let model = strongSelf.updateModel(response)
  strongSelf.updateUI(model)
}

Not Preferred

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

Not Preferred

swift
// 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)
}

<h2 id="access-control"> Access Control </h2>

訪問(wèn)修飾符應(yīng)該放在靠前的位置，前面只能有static、@IBAction 和 @IBOutlet。

Preferred:

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

Not Preferred:

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

對(duì)于全局的定義，一點(diǎn)顯示的標(biāo)示訪問(wèn)修飾符

頂層的函數(shù)、類(lèi)型、變量總是應(yīng)該顯示的指明訪問(wèn)修飾符:

swift
public var whoopsGlobalState: Int
internal struct TheFez {}
private func doTheThings(things: [Thing]) {}

但是對(duì)于不少頂層的聲明，如果可以盡量不要顯示指定訪問(wèn)修飾符:

swift
internal struct TheFez {
    var owner: Person = Joshaber()
}

對(duì)于頂層的(全局的)聲明很少有被指定為 internal 的情況，顯示的指明訪問(wèn)修飾符可以保證這個(gè)頂層聲明的設(shè)計(jì)是被充分考慮過(guò)的。但在這些聲明里面，使用已有的訪問(wèn)修飾符是更好的方式。

<h2 id="control-flow"> Control Flow </h2>

相比于 while-condition-increment 格式的循環(huán)，請(qǐng)盡量使用 for-in 這種方式。

Preferred:

swift
for _ in 0..<3 {
  print("Hello three times")
}

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

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

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

Not Preferred:

swift
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
}

<h2 id="golden-path"> Golden Path </h2>

嵌套的if會(huì)讓代碼的縮進(jìn)層次不齊（整齊的縮進(jìn)被稱(chēng)作Golden Path），會(huì)讓代碼可讀性變差，使用guard來(lái)做函數(shù)輸入合法性檢查，可以減少if嵌套。

Preferred:

swift
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
}

Not Preferred:

swift
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
  }
}

Preferred:

swift
guard let number1 = number1, 
        number2 = number2, 
        number3 = number3 else { 
        fatalError("impossible") 
}
// do something with numbers

Not Preferred:

swift
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")
}

<h3 id="failing-guards"> Failing Guards </h3>

Guard檢查失敗執(zhí)行的語(yǔ)句應(yīng)該退出當(dāng)前方法，并且應(yīng)該只有一條語(yǔ)句，如return, throw, break, continue, and fatalError()。如果需要多行語(yǔ)句，考慮使用defer。

<h2 id="semicolons"> Semicolons </h2>

Swift并不要求每行語(yǔ)句都必須以冒號(hào)結(jié)束，除了你需要在一行寫(xiě)多個(gè)語(yǔ)句的情況下。

建議不要在一行寫(xiě)多個(gè)語(yǔ)句。

這條規(guī)則的唯一例外是for-conditional-increment語(yǔ)句。但是我們推薦使用for-in來(lái)代替?zhèn)鹘y(tǒng)的for語(yǔ)句。

Preferred:

swift
let swift = "not a scripting language"

Not Preferred:

swift
let swift = "not a scripting language";

NOTE: Swift不像JavaScript那樣認(rèn)為省略掉句尾的冒號(hào)是不安全的

<h2 id="parentheses"> Parentheses </h2>

包住條件語(yǔ)句的圓括號(hào)應(yīng)該省略。

Preferred:

swift
if name == "Hello" {
  print("World")
}

Not Preferred:

swift
if (name == "Hello") {
  print("World")
}

<h2 id="use-whitespace-around-operator-definitions"> Use whitespace around operator definitions </h2>

在自定義操作符的時(shí)候，使用空格作為分割符:

Preferred:

swift
func <| (lhs: Int, rhs: Int) -> Int
func <|< <A>(lhs: A, rhs: A) -> A

Not Preferred:

swift
func <|(lhs: Int, rhs: Int) -> Int
func <|<<A>(lhs: A, rhs: A) -> A

如果構(gòu)成操作符的字符后面立即跟隨類(lèi)型或者參數(shù)的字符，將使其可讀性變差。加入合適的空格將讓它看起來(lái)更加清晰。

<h2 id="和xcode集成的格式檢查工具"> 和Xcode集成的格式檢查工具 </h2>
SwiftLint是開(kāi)源社區(qū)貢獻(xiàn)的一個(gè)Swift格式檢查工具，可以較好的和Xcode集成，并提供warning、errors和修復(fù)提示的工具。它使用的規(guī)則基本遵循GitHub's Swift Style Guide，是團(tuán)隊(duì)很好的統(tǒng)一格式的一個(gè)輔助工具。

<h2 id="document-revision-history"> Document Revision History </h2>

• 2016-11-11 Created by xdyang
• 2016-11-30 修改搜索跳轉(zhuǎn)方式