《從零開始學Swift》學習筆記（Day 57）——Swift編碼規範之凝視規範：文件凝視、文檔凝視、代碼凝視、使用地標凝視
前面說到Swift凝視的語法有兩種：單行凝視（//）和多行凝視（/*...*/）。這裏來介紹一下他們的使用規範。
1、文件凝視
文件凝視就在每個文件開頭加入凝視，文件凝視通常包含例如以下信息：版權信息、文件名稱、所在模塊、作者信息、歷史版本號信息、文件內容和作用等。
以下看一個文件凝視的演示樣例：
/* Copyright (C) 2015 Eorient Inc. All Rights Reserved. See LICENSE.txt for this sample’s licensing information Description: This file contains the foundational subclass of NSOperation. History: 15/7/22: Created by Tony Guan. 15/8/20: Add socket library 15/8/22: Add math library */
這個凝視僅僅是提供了版權信息、文件內容和歷史版本號信息等。文件凝視要依據自己實際情況包含內容。
2、文檔凝視
文檔凝視就是這樣的凝視內容能夠生成API幫助文檔。
文檔凝視主要對類型、屬性、方法或函數等功能。
文檔凝視是略微將單行凝視（//）和多行凝視（/*...*/）做一點“手腳”後。就成為了文檔凝視。單行文檔凝視（///）和多行文檔凝視（/**...*/）。
以下代碼演示樣例：
import Foundation
/**
The protocol that types may implement if they wish to be
notified of significant operation lifecycle events.
*/
protocol OperationObserver {
/// Invoked immediately prior to the `Operation`‘s `execute()` method.
func operationDidStart(operation: Operation)
}
代碼中使用了文檔凝視。
能夠使用一些工具將這些文檔凝視生成API文件
3、代碼凝視
程序代碼中處理文檔凝視還須要在一些關鍵的地方加入代碼凝視，文檔凝視通常是給一些看不到源碼的人看的幫助文檔。而代碼凝視是給閱讀源碼人參考的。
代碼凝視通常是採用單行凝視（//）和多行凝視（/*...*/）。
有的時候也會在代碼的尾端進行凝視。這要求凝視內容極短，應該在有足夠的空白來分開代碼和凝視。尾端凝視演示樣例代碼例如以下：
init(timeout: NSTimeInterval) {
self.timeout = timeout //初始化
}
4、使用地標凝視
隨著編碼過程深入，project代碼量會添加，不論什麽在這大量的代碼中能高速找到須要方法或者是剛才改動過代碼呢？
在Swift代碼中使用地標凝視，然後就能夠使用Xcode工具在代碼中高速查找了。
地標凝視有三個：
MARK，用於方法或函數的凝視。
TODO，表示這裏代碼有沒有完畢。還要處理。
FIXME，表示這裏改動了代碼。
這些凝視會出如今Xcode的 Jump Bar中。來看一個演示樣例：
class ViewController: UIViewController,
êUITableViewDataSource, UITableViewDelegate {
var listTeams: [[String:String]]!
override func viewDidLoad() {
super.viewDidLoad()
...
}
override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
//TODO: 釋放資源 //使用TODO凝視
}
// MARK: UITableViewDataSource 協議方法 //使用MARK凝視
func tableView(tableView: UITableView,
ênumberOfRowsInSection section: Int) -> Int {
return self.listTeams.count
}
func tableView(tableView: UITableView,
êcellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
let cellIdentifier = "CellIdentifier"
let cell: UITableViewCell! = tableView
ê.dequeueReusableCellWithIdentifier(cellIdentifier,
êforIndexPath: indexPath) as? UITableViewCell
// FIXME: 改動bug //使用了FIXME凝視
let row = indexPath.row
let rowDict = self.listTeams[row] as [String:String]
...
return cell
}
// MARK: UITableViewDelegate 協議方法 //使用MARK凝視
func tableView(tableView: UITableView,
êdidSelectRowAtIndexPath indexPath: NSIndexPath) {
...
}
}
上述代碼中使用三種地標凝視，在使用時候後面要跟有一個冒號(:)。
凝視之後假設使用呢？打開Xcode的 Jump Bar。例如以下圖。這些地標凝視會在下拉列表中粗體顯示。點擊列表項就會跳轉到凝視行。
歡迎關註關東升新浪微博@tony_關東升。
關註智捷課堂微信公共平臺，了解最新技術文章、圖書、教程信息
?
很多其它精品iOS、Cocos、移動設計課程請關註智捷課堂官方站點：http://www.zhijieketang.com
智捷課堂論壇站點：http://51work6.com/forum.php
《從零開始學Swift》學習筆記（Day 57）——Swift編碼規範之凝視規範：文件凝視、文檔凝視、代碼凝視、使用地標凝視