Google Swift Style Guide 浓缩版

参考文档： Google Swift Style Guide

源文件组织

文件名

所有 swift 源文件都使用 .swift 扩展名。

通常使用源文件中主体（primary entity）命名。如果是扩展现有类型，在现有类型有使用 + 号，带上扩展的内容。

例子：

• 如果是一个单一的类型 MyType，那么文件名为 MyType.swift。

• 如果是扩展 MyType 实现 MyProtocol，那么文件名为 MyType+MyProtocol.swift。

• 如果是给 MyType 增加了一下扩展方法，那么文件的前缀是 MyType+ ，比如可以是 MyType+Additions.swift。

• 如果文件里的声明不是在一个相关类型下，可以描述这些声明的作用、场景。比如 Math.swift。

Import 声明

默认直接 import 最高级的 module。显式导入使用的所有模块，比如虽然 UIKit 依赖 Foundation，但是如果使用 UIKit，还是会分别导入这两个 module。

只有在 import 最高级不能访问到需要的对象，或者为了避免污染到现有的命名空间里的对象才会 import 子模块。

Import 声明在文件的顶部。

不同的 import 类型用换行隔开。

例子：

import CoreLocation
import MyThirdPartyModule
import SpriteKit
import UIKit

import func Darwin.C.isatty

@testable import MyModuleUnderTest

 

Type, Variable, Function 的声明

通常一个源文件里只有一个顶级的类型声明，特别是这个类型的内容很多的时候。不过有的场景下一个文件里包含几个有关联的类型也是合理的，比如：

• 一个类和它的代理协议定义在同一个文件里。

• 一个类型和它相关的 helper 方法有时会定义在同一个文件里。这个时候通常会使用 fileprivate 修饰 helper 方法。

类型、变量、函数在源文件中的布局顺序对代码的可读性有很大的影响。但是这些的顺序并没有一个固定的形式，不同的类型、不同的文件可能会有不同的组织形式。

重要的是__每一个文件、类型必须按照一定的逻辑来组织这些元素__，也就是说如果别人问起为什么这样分布可以有一个说法。比如往一个类型里增加了一些方法，肯定不能只是简单追加在文件的末尾。当然你也可以说是按照方法写的时间顺序来组织，然而时间顺序并不是一种逻辑上的组织。

在组织这些元素时建议使用 // MARK: 来为分组写上注释。

class MovieRatingViewController: UITableViewController {

  // MARK: - View controller lifecycle methods

  override func viewDidLoad() {
    // ...
  }

  override func viewWillAppear(_ animated: Bool) {
    // ...
  }

  // MARK: - Movie rating manipulation methods

  @objc private func ratingStarWasTapped(_ sender: UIButton?) {
    // ...
  }

  @objc private func criticReviewWasTapped(_ sender: UIButton?) {
    // ...
  }
}

 

重载的声明放在一起

如果一个类型有多个初始化方法或者 subscript，或者一个文件、类型有多个基本名字相同的方法（参数标签不同），要把它们写在一起。

Extension 里的方法也要按照逻辑组织

Extension 的方法可能被几个不同的场景使用到。按照逻辑组织 Extension 里的成员也同样重要。也要按照一定的逻辑关系组织里面的元素。

通用格式

见文档：通用格式

专有结构的格式

非文档类注释

非文档类注释使用 // ，不使用 C 风格的 /* … */ 。

属性

变量声明的地方尽量靠近在使用的地方。

每一行只声明一个变量。

×
var a = 5, b = 10

 

Switch

Case 的声明和 switch 保持同样的缩进，case 里的内容换行后有 2 个缩进。

√
switch order {
case .ascending:
  print("Ascending")
case .descending:
  print("Descending")
case .same:
  print("Same")
}
×
switch order {
  case .ascending:
    print("Ascending")
  case .descending:
    print("Descending")
  case .same:
    print("Same")
}
×
switch order {
case .ascending:
print("Ascending")
case .descending:
print("Descending")
case .same:
print("Same")
}

 

Enum

通常 enum 下的每个 case 都是单独一行。只有在确认未来不会扩展，不需要给 case 单独写注释，没有使用关联类型，没有 rawValue 值的 enum 才有可能写成一行的。

√
public enum Token {
  case comma
  case semicolon
  case identifier
}

public enum Token {
  case comma, semicolon, identifier
}

public enum Token {
  case comma
  case semicolon
  case identifier(String)
}

 

×
public enum Token {
  case comma, semicolon, identifier(String)
}

如果每一个 case 都是 indirect，那么直接在 enum 上声明 indirect。

 

√
public indirect enum DependencyGraphNode {
  case userDefined(dependencies: [DependencyGraphNode])
  case synthesized(dependencies: [DependencyGraphNode])
}
×
public enum DependencyGraphNode {
  indirect case userDefined(dependencies: [DependencyGraphNode])
  indirect case synthesized(dependencies: [DependencyGraphNode])
}

枚举的选项顺序必须有意义。如果没有特别的逻辑可以参考，按照每项的首字母顺序。

下面的例子用空行分组，整体上按照状态码从小到达排序看起来很清楚：

 

√
public enum HTTPStatus: Int {
  case ok = 200

  case badRequest = 400
  case notAuthorized = 401
  case paymentRequired = 402
  case forbidden = 403
  case notFound = 404

  case internalServerError = 500
}

如果直接按照首字母的词典书序则会降低了可读性。

 

×
public enum HTTPStatus: Int {
  case badRequest = 400
  case forbidden = 403
  case internalServerError = 500
  case notAuthorized = 401
  case notFound = 404
  case ok = 200
  case paymentRequired = 402
}

尾闭包

如果两个函数只有最后一个闭包参数不同，那么就不应该重载。需要声明不同的函数名。如果只是尾参数闭包不同，那么如果使用了尾闭包的语法糖调用，会造成歧义，不知道调用的是哪个函数。

比如下面的例子，调用 greet 的时候就不知道调用的是哪个函数：

 

×
func greet(enthusiastically nameProvider: () -> String) {
  print("Hello, \(nameProvider())! It's a pleasure to see you!")
}

func greet(apathetically nameProvider: () -> String) {
  print("Oh, look. It's \(nameProvider()).")
}

greet { "John" }  // error: ambiguous use of 'greet'

如果函数调用的参数分成了很多行，这个时候不使用尾闭包的语法糖。

 

√
UIView.animate(
  withDuration: 0.5,
  animations: {
    // ...
  },
  completion: { finished in
    // ...
  })

×
UIView.animate(
  withDuration: 0.5,
  animations: {
    // ...
  }) { finished in
    // ...
  }

如果参数闭包符合尾闭包的定义，那么应该总是使用尾闭包的语法糖。只有两种例外情况：

• 前面提到的有重载的函数，使用尾闭包会导致歧义。

• 如果尾闭包用在条件控制语句中，尾闭包会引起语法的冲突。

 

√
Timer.scheduledTimer(timeInterval: 30, repeats: false) { timer in
  print("Timer done!")
}

if let firstActive = list.first(where: { $0.isActive }) {
  process(firstActive)
}

 

×
Timer.scheduledTimer(timeInterval: 30, repeats: false, block: { timer in
  print("Timer done!")
})

// This example fails to compile.
if let firstActive = list.first { $0.isActive } {
  process(firstActive)
}

使用尾闭包时，删除尾闭包外的括号：

 

√
let squares = [1, 2, 3].map { $0 * $0 }

×
let squares = [1, 2, 3].map({ $0 * $0 })
let squares = [1, 2, 3].map() { $0 * $0 }

尾部逗号

赋值数组、字典时每个元素分别占有一行时，最后一个选项后面也添加逗号。这样未来如果有元素加入会更加方便。

 

√
let configurationKeys = [
  "bufferSize",
  "compression",
  "encoding",                                    
]
×
let configurationKeys = [
  "bufferSize",
  "compression",
  "encoding"                                     
]

数字字面量

如果是一个很长的数字时，建议使用下划线按照语言习惯三位或者四位一组分割连接。

 

√
let number = 100_0000

Attribute

带参数的特性（比如 @availability(…)、@objc(…)）单独声明在一行里。

 

√
@available(iOS 9.0, *)
public func coolNewFeature() {
  // ...
}
×
@available(iOS 9.0, *) public func coolNewFeature() {
  // ...
}

不带参数的特性（比如 @IBOutlet、@NSManaged）则声明在同一行里。如果写到同一行后代码长度超过长度限制，则将特性标签单独声明一行。

 

√
public class MyViewController: UIViewController {
  @IBOutlet private var tableView: UITableView!
}

 

命名

Apple’s API Style Guidelines

认真贯彻学习苹果官方发布的 API design guidelines。

不要使用约定命名样式代替访问控制

如果要控制访问权限应该使用访问控制（internal、fileprivate、private），不用使用自定义的命名方式来区分，比如在方法前前下划线表示私有。

只有在极端的情况下才会采用这种自定义命名表示。比如有一个方法只是为了某个模板调用才公开的，这种情况下本意是私有的，但是又必须声明成 public，可以使用自定义的命名惯例。

标识符

通常，标识符只包含 7 位 ASCII 字符。如果 Unicode 标识符在代码库的问题域中有明确含义(例如，表示数学概念的希腊字母)，并且能被使用该代码的团队很好地理解，则可以使用它们。

初始化方法

如果初始化参数和自身的属性是一一对应的关系，参数名和属性名保持一致。

 

√
public struct Person {
  public let name: String
  public let phoneNumber: String

  // GOOD.
  public init(name: String, phoneNumber: String) {
    self.name = name
    self.phoneNumber = phoneNumber
  }
}

 

×
public struct Person {
  public let name: String
  public let phoneNumber: String

  // AVOID.
  public init(name otherName: String, phoneNumber otherPhoneNumber: String) {
    name = otherName
    phoneNumber = otherPhoneNumber
  }
}

 

静态属性

如果一个静态属性返回的是自身的类型，不用在属性名称后缀中重复声明类型。

√
public class UIColor {
  public class var red: UIColor {                // GOOD.
    // ...
  }
}

public class URLSession {
  public class var shared: URLSession {          // GOOD.
    // ...
  }
}

 

×
public class UIColor {
  public class var redColor: UIColor {           // AVOID.
    // ...
  }
}

public class URLSession {
  public class var sharedSession: URLSession {   // AVOID.
    // ...
  }
}

如果是表示单例的静态属性，一般命名为 shared 或者 default。

全局常量

就像正常变量一样使用匈牙利命名方式，不要在前面加上 g、k 或其他特别的格式。

 

√
let secondsPerMinute = 60
×
let SecondsPerMinute = 60
let kSecondsPerMinute = 60
let gSecondsPerMinute = 60
let SECONDS_PER_MINUTE = 60

 

代理方法

代理方法的命名和正常函数命名会有明显的区别，命名的方式参考了 Cocoa 的 protocol。

代理的主体作为方法第一个参数。

只有一个参数

如果返回值是 void，方法名以主体开头，接一个动词短语表示发生的事件。隐藏参数名称标签。

 

√
func scrollViewDidBeginScrolling(_ scrollView: UIScrollView)

如果返回值是 Bool，方法名以主体开头，接一个表示判断的短语。隐藏参数名称标签。

 

√
func scrollViewShouldScrollToTop(_ scrollView: UIScrollView) -> Bool

如果返回的是其他类型的值，方法名则是一个描述了返回值角色的名词短语。参数标签会尽量使用介词或者词组来连接方法名和主体。

 

√
func numberOfSections(in scrollView: UIScrollView) -> Int

多个参数

代理方法多个参数的情况下，第一个参数总是隐藏标签。

命名的分类与上面提到的相似，区别只是方法的基础名字都是主体，对于方法的具体作用描述声明在参数标签里。

 

√
func tableView(
  _ tableView: UITableView,
  willDisplayCell cell: UITableViewCell,
  forRowAt indexPath: IndexPath)

func tableView(
  _ tableView: UITableView,
  shouldSpringLoadRowAt indexPath: IndexPath,
  with context: UISpringLoadedInteractionContext
) -> Bool

func tableView(
  _ tableView: UITableView,
  heightForRowAt indexPath: IndexPath
) -> CGFloat