Swift— Swift编码规范之命名规范-备

程序代码中到处都是自己定义的名字，取一个有样并且符合规范的名字非常重要。

命名方法很多，但是比较有名的，广泛接受命名法有：

• 匈牙利命名，一般只是命名变量，原则是：变量名=类型前缀+描述，如bFoo表示布尔类型变量，pFoo表示指针类型变量。匈牙利命名还是有一定争议的，在Swift编码规范中几本不采用匈牙利命名。

• 驼峰命名（Camel-Case），又称骆驼命名法，是指混合使用大小写字母来名字。驼峰命名又分为：小驼峰法和大驼峰法。

  1. 小驼峰法是第一个单词是全部小写，后面的单词首字母大写，如：myRoomCount；

  2. 大驼峰法是第一个单词的首字母也大写，如：ClassRoom。 

驼峰命名是Swift编码规范主要的命名方法，更加所命名的内容不同，可以选择小驼峰法还是大驼峰法。下面分类说明一下：

• 对类、结构体、枚举和协议等类型命名，应该采用大驼峰法，如SplitViewController。

• 文件名，采用大驼峰法，如BlockOperation.swift。

• 扩展文件，有的时候扩展是定义在一个独立的文件中的，它的命名是“原始类型名+扩展名”作为扩展文件名，如NSOperation+Operations.swift。

• 变量和属性，采用应该采用小驼峰法，如studentNumber。

• 常量，采用大驼峰法，如MaxStudentNumber。

• 枚举成员，与常量类似，采用大驼峰法，如ExecutionFailed。

• 函数和方法，采用应该采用小驼峰法，如balanceAccount、isButtonPressed等。

=================================

前面说到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、使用地标注释

随着编码过程深入，工程代码量会增加，任何在这大量的代码中能快速找到需要方法或者是刚才修改过代码呢？

在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，如下图，这些地标注释会在下拉列表中粗体显示，点击列表项就会跳转到注释行。

 ===============================

声明是在声明变量、常量、属性、方法或函数和自定义类型时候需要遵守的规范。

首先变量或常量时每行声明变量或常量的数量推荐一行一个，因为这样以利于写注释。示例代码如下。

推荐使用：

 

let level = 0

var size = 10

 

不推荐使用：

 

let level = 0; var size = 10

变量或常量的数据类型，如果有可能应尽可能采用类型推断，这样代码很简洁。示例代码如下。

推荐使用：

 

let level = 0

var size = 10

不推荐使用：

 

let level: Int = 0

var size: Int = 10

如果不是默认数据类型，需要明确声明变量或常量的数据类型。示例代码如下。

 

let level: Int8 = 0

var size: Int64 = 10

在指定数据类型时候需要使用冒号（:），size与冒号之间没有空格，冒号和数据类型之间要有一个空格。示例代码如下。

推荐使用：

 

let level: Int8 = 0

var size: Int64 = 10

不推荐使用：

 

let level : Int8 = 0

var size:Int64 = 10

使用数据类型时尽可能使用Swift本身数据类型，例如：

推荐使用：

 

let width = 120.0

let widthString = "Hello."

var deviceModels: [String]

var employees: [Int: String]

不推荐使用：

let  NSNumber = 120.0

let widthString: NSString  = "Hello."

var deviceModels: NSArray

var employees: NSDictionary

属性声明

属性包括存储属性和计算属性，如果是存储属性的声明规范与变量或常量声明的规范是一样的。如果是计算属性类似于代码块，在使用只读计算属性时候，如果可能要省略get语句。示例代码如下。

推荐使用：

var fullName : String {

    return firstName + "." + lastName

}

不推荐使用：

 

var fullName : String {

    get {

        return firstName + "." + lastName

    }

}