《从零開始学Swift》学习笔记（Day 57）——Swift编码规范之凝视规范：文件凝视、文档凝视、代码凝视、使用地标凝视

转载

mob604756ee0e6c 2017-07-31 20:23:00

文章标签 ide xcode 帮助文档 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) {
        ...
    }
}