注: Copy 自 cocoachina?

英文原文：Swift Style Guide

翻譯作者：碼農(nóng)網(wǎng) – 豆照建

1. 代碼格式

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 左大括號不用另起一行。

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

1.6 當在寫一個變量類型锐极，一個字典里的主鍵盒齿，一個函數(shù)的參數(shù)，遵從一個協(xié)議枚荣，或一個父類碗脊，不用在分號前添加空格。

// 指定類型let pirateViewController: PirateViewController// 字典語法(注意這里是向左對齊而不是分號對齊)let ninjaDictionary: [String: AnyObject] = [ "fightLikeDairyFarmer": false, "disgusting": true]// 聲明函數(shù)func myFunction

1.7 基本來說橄妆，要在逗號后面加空格衙伶。

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

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

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

1.9 遵守Xcode內(nèi)置的縮進格式( 如果已經(jīng)遵守矢劲，按下CTRL-i 組合鍵文件格式?jīng)]有變化)。當聲明的一個函數(shù)需要跨多行時慌随，推薦使用Xcode默認的格式卧须，目前Xcode 版本是 7.3。

// Xcode針對跨多行函數(shù)聲明縮進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 當調(diào)用的函數(shù)有多個參數(shù)時儒陨，每一個參數(shù)另起一行花嘶，并比函數(shù)名多一個縮進。

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

1.11 當遇到需要處理的數(shù)組或字典內(nèi)容較多需要多行顯示時蹦漠，需把 [ 和 ] 類似于方法體里的括號椭员， 方法體里的閉包也要做類似處理。

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 應盡量避免出現(xiàn)多行斷言笛园，可使用本地變量或其他策略隘击。

// 推薦let firstCondition = x == firstReallyReallyLongPredicateFunctionlet secondCondition = y == secondReallyReallyLongPredicateFunctionlet thirdCondition = z == thirdReallyReallyLongPredicateFunctionif firstCondition && secondCondition && thirdCondition { // 你要干什么}// 不推薦if x == firstReallyReallyLongPredicateFunction && y == secondReallyReallyLongPredicateFunction && z == thirdReallyReallyLongPredicateFunction { // 你要干什么}

2. 命名

2.1 在Swift中不用如Objective-C式 一樣添加前綴 (如使用 GuybrushThreepwoode 而不是 LIGuybrushThreepwood)。

2.2 使用帕斯卡拼寫法（又名大駱駝拼寫法研铆，首字母大寫）為類型命名 (如 struct, enum, class, typedef, associatedtype 等)埋同。

2.3 使用小駱駝拼寫法 (首字母小寫) 為函數(shù)，方法棵红，變量凶赁，常量，參數(shù)等命名。

2.4 首字母縮略詞在命名中一般來說都是全部大寫虱肄，例外的情形是如果首字母縮略詞是一個命名的開始部分致板，而這個命名需要小寫字母作為開頭，這種情形下首字母縮略詞全部小寫咏窿。

// "HTML" 是變量名的開頭, 需要全部小寫 "html"let htmlBodyContent: String = "

Hello, World!

" // 推薦使用 ID 而不是 Id let profileID: Int = 1 // 推薦使用 URLFinder 而不是 UrlFinder class URLFinder { /* ... */ }

2.5 使用前綴 k + 大駱駝命名法 為所有非單例的靜態(tài)常量命名斟或。

class MyClassName { // 基元常量使用 k 作為前綴 static let kSomeConstantHeight: CGFloat = 80.0 // 非基元常量也是用 k 作為前綴 static let kDeleteButtonColor = UIColor.redColor // 對于單例不要使用k作為前綴 static let sharedInstance = MyClassName /* ... */}

2.6 對于泛型和關聯(lián)類型，可以使用單個大寫字母集嵌，也可是遵從大駱駝命名方式并能描述泛型的單詞萝挤。如果這個單詞和要實現(xiàn)的協(xié)議或繼承的父類有沖突，可以為相關類型或泛型名字添加 Type 作為后綴根欧。

class SomeClass

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 如果原有命名不能明顯表明類型，則屬性命名內(nèi)要包括類型信息侈沪。

// 推薦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 時蕉陋，變量名內(nèi)應包含類型名捐凭。 // 這里建議使用 firstNameLabel @IBOutlet weak var firstName: UILabel!}

2.10 當給函數(shù)參數(shù)命名時，要確保函數(shù)能理解每個參數(shù)的目的凳鬓。

2.11 根據(jù)蘋果接口設計指導文檔, 如果協(xié)議描述的是協(xié)議做的事應該命名為名詞(如Collection) 茁肠，如果描述的是行為，需添加后綴 able 或 ing (如Equatable 和 ProgressReporting)缩举。 如果上述兩者都不能滿足需求垦梆，可以添加Protocol作為后綴匹颤，例子見下面。

// 這個協(xié)議描述的是協(xié)議能做的事奶赔，應該命名為名詞。protocol TableViewSectionProvider { func rowHeight(atRow row: Int) -> CGFloat var numberOfRows: Int { get } /* ... */}// 這個協(xié)議表達的是行為, 以able最為后綴protocol Loggable { func logCurrentState /* ... */}// 因為已經(jīng)定義類InputTextView杠氢，如果依然需要定義相關協(xié)議，可以添加Protocol作為后綴。protocol InputTextViewProtocol { func sendTrackingEvent func inputText -> String /* ... */}

3. 代碼風格

3.1 綜合

3.1.1 盡可能的多使用let扫腺，少使用var严望。

3.1.2 當需要遍歷一個集合并變形成另一個集合時，推薦使用函數(shù) 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(integer) }}

3.1.3 如果變量類型可以依靠推斷得出因悲，不建議聲明變量時指明類型。

3.1.4 如果一個函數(shù)有多個返回值勺爱，推薦使用 元組 而不是 inout 參數(shù)晃琳， 如果你見到一個元組多次，建議使用typealias 琐鲁，而如果返回的元組有三個或多于三個以上的元素卫旱，建議使用結構體或類。

func pirateName -> (firstName: String, lastName: String) { return ("Guybrush", "Threepwood")}let name = pirateNamelet firstName = name.firstNamelet lastName = name.lastName

3.1.5 當使用委托和協(xié)議時围段，請注意避免出現(xiàn)循環(huán)引用顾翼，基本上是在定義屬性的時候使用 weak 修飾。

3.1.6 在閉包里使用 self 的時候要注意出現(xiàn)循環(huán)引用奈泪，使用捕獲列表可以避免這一點适贸。

myFunctionWithClosure { [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 在使用類方法的時候不用簡寫冯遂，因為類方法不如 枚舉 類型一樣砾隅，可以根據(jù)輕易地推導出上下文。

// 推薦imageView.backgroundColor = UIColor.whiteColor// 不推薦imageView.backgroundColor = .whiteColor

3.1.11 不建議使用用self.修飾除非需要债蜜。

3.1.12 在新寫一個方法的時候晴埂，需要衡量這個方法是否將來會被重寫，如果不是寻定，請用 final 關鍵詞修飾儒洛，這樣阻止方法被重寫。一般來說狼速，final 方法可以優(yōu)化編譯速度琅锻，在合適的時候可以大膽使用它。但需要注意的是，在一個公開發(fā)布的代碼庫中使用 final 和本地項目中使用 final 的影響差別很大的恼蓬。

3.1.13 在使用一些語句如 else惊完，catch等緊隨代碼塊的關鍵詞的時候，確保代碼塊和關鍵詞在同一行处硬。下面 if/else 和 do/catch 的例子.

if someBoolean { // 你想要什么} else { // 你不想做什么}do { let fileContents = try readFile("filename.txt")} catch { print(error)}

3.2 訪問控制修飾符

3.2.1 如果需要把訪問修飾符放到第一個位置小槐。

// 推薦private static let kMyPrivateNumber: Int// 不推薦static private let kMyPrivateNumber: Int

3.2.2 訪問修飾符不應單獨另起一行，應和訪問修飾符描述的對象保持在同一行荷辕。

// 推薦public class Pirate { /* ... */}// 不推薦publicclass Pirate { /* ... */}

3.2.3 默認的訪問控制修飾符是 internal, 如果需要使用internal 可以省略不寫凿跳。

3.2.4 當一個變量需要被單元測試 訪問時，需要聲明為 internal 類型來使用@testable import {ModuleName}疮方。 如果一個變量實際上是private 類型控嗜，而因為單元測試需要被聲明為 internal 類型，確定添加合適的注釋文檔來解釋為什么這么做骡显。這里添加注釋推薦使用 - warning: 標記語法疆栏。

/** 這個變量是private 名字 - warning: 定義為 internal 而不是 private 為了 `@testable`. */let pirateName = "LeChuck"

3.3 自定義操作符

不推薦使用自定義操作符，如果需要創(chuàng)建函數(shù)來替代惫谤。

在重寫操作符之前承边，請慎重考慮是否有充分的理由一定要在全局范圍內(nèi)創(chuàng)建新的操作符，而不是使用其他策略石挂。

你可以重載現(xiàn)有的操作符來支持新的類型(特別是 ==)博助，但是新定義的必須保留操作符的原來含義，比如 == 必須用來測試是否相等并返回布爾值痹愚。

3.4 Switch 語句 和 枚舉

3.4.1 在使用 Switch 語句時富岳，如果選項是有限集合時，不要使用default拯腮，相反地窖式，把一些不用的選項放到底部，并用 break 關鍵詞 阻止其執(zhí)行动壤。

3.4.2 因為Swift 中的 switch 選項默認是包含break的萝喘， 如果不需要不用使用 break 關鍵詞。

3.4.3 case 語句 應和 switch 語句左對齊琼懊，并在 標準的 default 上面阁簸。

3.4.4 當定義的選項有關聯(lián)值時，確保關聯(lián)值有恰當?shù)拿Q哼丈，而不只是類型启妹。(如. 使用 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 的選項不應該觸發(fā)醉旦，可以拋出錯誤 或 斷言類似的做法饶米。

func handleDigit(digit: Int) throws { 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桨啃，在其他場景使用 非可選類型 和 常規(guī)可選類型，即使有的場景你確定有的變量使用的時候永遠不會為 nil檬输， 但這樣做可以保持一致性和程序更加健壯照瘾。

3.5.2 不要使用 as! 或 try!。

3.5.3 如果對于一個變量你不打算聲明為可選類型丧慈，但當需要檢查變量值是否為 nil析命，推薦用當前值和 nil 直接比較，而不推薦使用 if let 語法伊滋。

// 推薦if someOptional != nil { // 你要做什么}// 不推薦if let _ = someOptional { // 你要做什么}

3.5.4 不要使用 unowned碳却，unowned 和 weak 變量基本上等價队秩，并且都是隱式拆包( unowned 在引用計數(shù)上有少許性能優(yōu)化)笑旺，由于不推薦使用隱式拆包，也不推薦使用unowned 變量馍资。

// 推薦weak var parentViewController: UIViewController?// 不推薦weak var parentViewController: UIViewController!unowned var parentViewController: UIViewController3.5.5 當拆包取值時筒主，使用和被拆包取值變量相同的名稱。guard let myVariable = myVariable else { return}

3.6 協(xié)議

在實現(xiàn)協(xié)議的時候鸟蟹，有兩種方式來組織你的代碼:

使用 // MARK: 注釋來分割協(xié)議實現(xiàn)和其他代碼乌妙。

使用 extension 在 類/結構體已有代碼外，但在同一個文件內(nèi)建钥。

請注意 extension 內(nèi)的代碼不能被子類重寫藤韵，這也意味著測試很難進行。 如果這是經(jīng)常發(fā)生的情況熊经，為了代碼一致性最好統(tǒng)一使用第一種辦法泽艘。否則使用第二種辦法，其可以代碼分割更清晰镐依。

使用而第二種方法的時候匹涮，使用 // 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 computedProperty: String { get { if someBool { return "I'm a mighty pirate!" } return "I'm selling these fine leather jackets." } set { computedProperty = newValue } willSet { print("will set to (newValue)") } didSet { print("did set from (oldValue) to (newValue)") }}

3.7.4 在創(chuàng)建類常量的時候枫笛，使用 static 關鍵詞修飾来农。

class MyTableViewCell: UITableViewCell { static let kReuseIdentifier = String(MyTableViewCell) static let kCellHeight: CGFloat = 80.0}

3.7.5 聲明單例屬性可以通過下面方式進行：

class PirateManager { static let sharedInstance = PirateManager /* ... */}

3.8 閉包

3.8.1 如果參數(shù)的類型很明顯，可以在函數(shù)名里可以省略參數(shù)類型, 但明確聲明類型也是允許的崇堰。 代碼的可讀性有時候是添加詳細的信息沃于，而有時候部分重復涩咖，根據(jù)你的判斷力做出選擇吧，但前后要保持一致性繁莹。

// 省略類型doSomethingWithClosure { response in print(response)}// 明確指出類型doSomethingWithClosure { response: NSURLResponse in print(response)}// map 語句使用簡寫[1, 2, 3].flatMap { String($0) }

3.8.2 如果使用捕捉列表 或 有具體的非 Void返回類型檩互，參數(shù)列表應該在小括號內(nèi)， 否則小括號可以省略咨演。

// 因為使用捕捉列表闸昨，小括號不能省略。doSomethingWithClosure { [weak self] (response: NSURLResponse) in self?.handleResponse(response)}// 因為返回類型薄风，小括號不能省略饵较。doSomethingWithClosure { (response: NSURLResponse) -> String in return String(response)}

3.8.3 如果閉包是變量類型，不需把變量值放在括號中遭赂，除非需要循诉，如變量類型是可選類型(Optional?)， 或當前閉包在另一個閉包內(nèi)撇他。確保閉包里的所以參數(shù)放在小括號中茄猫，這樣表示沒有參數(shù)，Void 表示不需要返回值困肩。

let completionBlock: (success: Bool) -> Void = { print("Success? (success)")}let completionBlock: -> Void = { print("Completed!")}let completionBlock: ( -> Void)? = nil

3.9 數(shù)組

3.9.1 基本上不要通過下標直接訪問數(shù)組內(nèi)容划纽，如果可能使用如 .first 或 .last, 因為這些方法是非強制類型并不會崩潰。 推薦盡可能使用 for item in items 而不是 for i in 0..

3.9.2 不要使用 += 或 + 操作符給數(shù)組添加新元素锌畸，使用性能較好的.append 或.appendContentsOf 勇劣，如果需要聲明數(shù)組基于其他的數(shù)組并保持不可變類型， 使用 let myNewArray = [arr1, arr2].flatten潭枣，而不是let myNewArray = arr1 + arr2 比默。

3.10 錯誤處理

假設一個函數(shù) myFunction 返回類型聲明為 String，但是總有可能函數(shù)會遇到error卸耘，有一種解決方案是返回類型聲明為 String?, 當遇到錯誤的時候返回 nil退敦。

例子:

func readFile(withFilename filename: String) -> String? { guard let file = openFile(filename) else { return nil } let fileContents = file.read file.close return fileContents } func printSomeFile { let filename = "somefile.txt" guard let fileContents = readFile(filename) else { print("不能打開 (filename).") return } print(fileContents) }

實際上如果預知失敗的原因，我們應該使用Swift 中的 try/catch 蚣抗。

定義 錯誤對象 結構體如下:

struct Error: ErrorType { 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(withFilename filename: String) throws -> String { guard let file = openFile(filename) else { throw Error(message: “打不開的文件名稱 (filename).") } let fileContents = file.read file.close return fileContents } func printSomeFile { do { let fileContents = try readFile(filename) print(fileContents) } catch { print(error) } }

其實項目中還是有一些場景更適合聲明為可選類型侈百，而不是錯誤捕捉和處理，比如在獲取遠端數(shù)據(jù)過程中遇到錯誤翰铡，nil作為返回結果是合理的钝域，也就是聲明返回可選類型比錯誤處理更合理。

整體上說锭魔，如果一個方法有可能失敗例证，并且使用可選類型作為返回類型會導致錯誤原因湮沒，不妨考慮拋出錯誤而不是吃掉它迷捧。

3.11 使用 guard 語句

3.11.1 總體上织咧，我們推薦使用提前返回的策略胀葱，而不是 if 語句的嵌套。使用 guard 語句可以改善代碼的可讀性笙蒙。

// 推薦 func eatDoughnut(atIndex index: Int) { guard index >= 0 && index = 0 && index

3.11.2 在解析可選類型時抵屿，推薦使用 guard 語句，而不是 if 語句捅位，因為 guard 語句可以減少不必要的嵌套縮進轧葛。

// 推薦 guard let monkeyIsland = monkeyIsland else { return } bookVacation(onIsland: monkeyIsland) bragAboutVacation(onIsland: monkeyIsland) // 不推薦 if let monkeyIsland = monkeyIsland { bookVacation(onIsland: monkeyIsland) bragAboutVacation(onIsland: monkeyIsland) } // 禁止 if monkeyIsland == nil { return } bookVacation(onIsland: monkeyIsland!) bragAboutVacation(onIsland: monkeyIsland!)

3.11.3 當解析可選類型需要決定在 if 語句 和 guard 語句之間做選擇時，最重要的判斷標準是是否讓代碼可讀性更強艇搀，實際項目中會面臨更多的情景尿扯，如依賴 2 個不同的布爾值，復雜的邏輯語句會涉及多次比較等焰雕，大體上說衷笋，根據(jù)你的判斷力讓代碼保持一致性和更強可讀性， 如果你不確定 if 語句 和 guard 語句哪一個可讀性更強淀散，建議使用 guard 右莱。

// if 語句更有可讀性 if operationFailed { return } // guard 語句這里有更好的可讀性 guard isSuccessful else { return } // 雙重否定不易被理解 - 不要這么做 guard !operationFailed else { return }

3.11.4 如果需要在2個狀態(tài)間做出選擇蚜锨，建議使用if 語句档插，而不是使用 guard 語句。

// 推薦 if isFriendly { print("你好, 遠路來的朋友亚再！") } else { print(“窮小子郭膛，哪兒來的？") } // 不推薦 guard isFriendly else { print("窮小子氛悬，哪兒來的则剃？") return } print("你好, 遠路來的朋友！")

3.11.5 你只應該在在失敗情形下退出當前上下文的場景下使用 guard 語句如捅，下面的例子可以解釋 if 語句有時候比 guard 語句更合適 – 我們有兩個不相關的條件棍现，不應該相互阻塞。

if let monkeyIsland = monkeyIsland { bookVacation(onIsland: monkeyIsland) } if let woodchuck = woodchuck where canChuckWood(woodchuck) { woodchuck.chuckWood }

3.11.6 我們會經(jīng)常遇到使用 guard 語句拆包多個可選值镜遣，如果所有拆包失敗的錯誤處理都一致可以把拆包組合到一起 (如 return, break, continue,throw 等).

// 組合在一起因為可能立即返回 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.") }

4. 文檔/注釋

4.1 文檔

如果一個函數(shù)比 O(1) 復雜度高己肮，你需要考慮為函數(shù)添加注釋，因為函數(shù)簽名(方法名和參數(shù)列表) 并不是那么的一目了然悲关，這里推薦比較流行的插件 VVDocumenter. 不論出于何種原因谎僻，如果有任何奇淫巧計不易理解的代碼，都需要添加注釋寓辱，對于復雜的 類/結構體/枚舉/協(xié)議/屬性 都需要添加注釋艘绍。所有公開的 函數(shù)/類/變量/枚舉/協(xié)議/屬性/常數(shù) 也都需要添加文檔，特別是 函數(shù)聲明(包括名稱和參數(shù)列表) 不是那么清晰的時候秫筏。

寫文檔時诱鞠，確保參照蘋果文檔中提及的標記語法合集挎挖。

在注釋文檔完成后，你應檢查格式是否正確航夺。

規(guī)則:

4.1.1 一行不要超過160個字符 (和代碼長度限制雷同).

4.1.2 即使文檔注釋只有一行肋乍，也要使用模塊化格式 (/** */).

4.1.3 注釋模塊中的空行不要使用 * 來占位。

4.1.4 確定使用新的 – parameter 格式敷存，而不是就得 Use the new -:param: 格式墓造，另外注意 parameter 是小寫的。

4.1.5 如果需要給一個方法的 參數(shù)/返回值/拋出異常 添加注釋锚烦，務必給所有的添加注釋觅闽，即使會看起來有部分重復，否則注釋會看起來不完整涮俄，有時候如果只有一個參數(shù)值得添加注釋蛉拙，可以在方法注釋里重點描述。

4.1.6 對于負責的類彻亲，在描述類的使用方法時可以添加一些合適的例子孕锄，請注意Swift注釋是支持 MarkDown 語法的。

/** ## 功能列表 這個類提供下一下很贊的功能苞尝，如下: - 功能 1 - 功能 2 - 功能 3 ## 例子 這是一個代碼塊使用四個空格作為縮進的例子畸肆。 let myAwesomeThing = MyAwesomeClass myAwesomeThing.makeMoney ## 警告 使用的時候總注意以下幾點 1. 第一點 2. 第二點 3. 第三點 */ class MyAwesomeClass { /* ... */ }

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 { /* ... */ } }