Swift 编程风格指南（raywenderlich.com 版本）

约定不等于承诺〃 2022-08-06 05:10 167阅读 0赞

官方 raywenderlich.com Swift 编程风格指南

![1405122209554][]

本文版权归 raywenderlich.com 、[The Official raywenderlich.com Swift Style Guide][]项目以及所有贡献者所有。译者翻译仅供知识传播使用。

本风格指南的目标是让Swift代码更简洁、可读更强。

### 语言 ###

推荐使用跟苹果API文档风格统一的英语。

推荐：

var color = "red"

不推荐：

var colour = "red"

### 空白 ###

*  使用2个空白符作为缩进，不要使用`Tab`制表符，请务必在`Xcode`中进行设置；
 *  方法定义时的大括号或其它大括号（`if`/`else`/`switch`/`while`等）中的左括号写在当前语句的结尾，右括号需要另起一行。

推荐：

if user.isHappy {
       
      //Do something
    } else {
       
      //Do something else
    }

if user.isHappy
    {
       
        //Do something
    }
    else {
       
        //Do something else
    }

*  方法定义之间需要插入一个空行，让代码在视觉上更清晰，也便于管理。方法内部也需要使用空行来分隔不同功能的代码块，但如果一个方法中有太多代码块，你最好将它们拆分为多个方法（重构）。

### 注释 ###

只有在必要的时候才写注释来解释某段代码为什么那么做。注释必须跟代码同步更新，该删掉时就删掉。

尽量避免使用多行注释，而是让代码本身去解释自己的功能。

### 命名 ###

使用可描述性的驼峰式命名法为类、函数、方法、变量等命名。模块中的类名和常量名首字母需要大写，而方法名和变量名的首字母需要小写。

推荐：

let MaximumWidgetCount = 100
    
    class WidgetContainer {
       
      var widgetButton: UIButton
      let widgetHeightPercentage = 0.85
    }

不推荐：

let MAX_WIDGET_COUNT = 100
    
    class app_widgetContainer {
       
      var wBut: UIButton
      let wHeightPct = 0.85
    }

对于函数和构造器（`init`），除非能一目了然，否则建议为每个参数命名。如果能让函数可读性更强，请提供每个参数的外部参数名。

func dateFromString(dateString: NSString) -> NSDate
    func convertPointAt(#column: Int, #row: Int) -> CGPoint
    func timedAction(#delay: NSTimeInterval, perform action: SKAction) -> SKAction!
    
    // would be called like this:
    dateFromString("2014-03-14")
    convertPointAt(column: 42, row: 13)
    timedAction(delay: 1.0, perform: someOtherAction)

对于类中的方法，请遵循苹果惯例，将方法名作为第一个参数的外部名：

class Guideline {
       
      func combineWithString(incoming: String, options: Dictionary?) {
        ... }
      func upvoteBy(amount: Int) {
        ... }
    }

如果在非代码文本（包括教程、书籍以及注释中）中引用了某个函数，请提供函数所有参数的外部参数名：

The dateFromString() function is great.
    Call convertPointAt(column:, row:) from your init() method.
    The return value of timedAction(delay:, perform:) may be nil.
    Guideline objects only have two methods: combineWithString(options:) and upvoteBy()
    You shouldn't call the data source method tableView(cellForRowAtIndexPath:) directly.

#### 类前缀 ####

Swift中的模块（`module`）包含了命名空间，所有在模块中定义的类型名都不会与其它模块冲突。所以我们不再需要使用前缀命名来减少命名冲突。如果两个来自不同模块的相同名字需要同时引用，你可以使用模块名+点+类型名的方式来处理：

import MyModule
    
    var myClass = MyModule.MyClass()

再次重申，请不要在Swift类型命名时加前缀。

如果你需要将Swift类型暴露给Objective-C，你可以为其指定一个在`Objective-C`中使用的合适前缀（请参考[ObjC编程风格指南][ObjC]：

@objc (RWTChicken) class Chicken {
       
       ...
    }

### 分号 ###

Swift不需要在每条语句后加分号。但如果将多条语句写在一行代码中，这时需要加上分号。 然而我们并不推荐这种将多行语句写在一行的做法。 唯一例外是`for-conditional-increment`结构，它必须使用分号。但你应该尽量使用`for-in`结构来替代这种行为： 推荐：

var swift = "not a scripting language"

不推荐：

var swift = "not a scripting language";

> 注意： Swift跟Javascript有很大区别，Javascript中如果忽略分号会被认为[造成代码的不安全][Link 1]。

### 类和结构体 ###

请将类和结构体中的代码按以下顺序进行组织：

*  变量和常量属性
 *  构造器
 *  公共方法
 *  私有方法

class Circle: Shape {
       
      var x: Int, y: Int
      var radius: Double
      var diameter: Double {
       
        get {
       
          return radius * 2
        }
        set {
       
          radius = newValue / 2
        }
      }
    
      init(x: Int, y: Int, radius: Double) {
       
        self.x = x
        self.y = y
        self.radius = radius
      }
    
      convenience init(x: Int, y: Int, diameter: Double) {
       
        self.init(x: x, y: y, radius: diameter / 2)
      }
    
      func describe() -> String {
       
        return "I am a circle at (\(x),\(y)) with an area of \(computeArea())"
      }
    
      func computeArea() -> Double {
       
        return M_PI * radius * radius
      }  
    }

上面的例子还展示了以下风格：

*  定义属性、变量、常量、参数以及其他语句时，在其后面加上空格，而不是在前面加。比如说，`x: Int` 和 `Circle: Shape`；
 *  属性的`getter`、`setter`以及属性观察器`willSet`和`didSet`的实现都需要缩进；
 *  如果多个变量和结构体有相同的使用目的或使用环境，可以将它们定义在同一行代码中。

### Self 的使用 ###

请避免在Swift中使用`self`，因为我们不需要使用`self`来访问一个对象的属性或调用它的方法。

唯一需要使用的场景是在类或结构体的构造器中。你可以使用`self`来区分传入的参数和类/结构体的属性：

class BoardLocation {
       
      let row: Int, column: Int
    
      init(row: Int,column: Int) {
       
        self.row = row
        self.column = column
      }
    }

### 函数定义 ###

尽量将较短的函数名定义在一行，并以一个左大括号结尾：

func reticulateSplines(spline: Double[]) -> Bool {
       
      // reticulate code goes here
    }

如果函数名较长，请在适当的时候换行，并对下一行函数名进行缩进：

func reticulateSplines(spline: Double[], adjustmentFactor: Double,
        translateConstant: Int, comment: String) -> Bool {
       
      // reticulate code goes here
    }

### 闭包 ###

请尽量使用`掉尾`（就是将最后一个闭包参数直接附在方法调用后，看起来像是控制语句的body一样）闭包语法。无论何时，请给闭包中每个参数一个描述性的名字：

return SKAction.customActionWithDuration(effect.duration) {
        node, elapsedTime in 
      // more code goes here
    }

> 笔者：[@aemaeth][aemaeth] 提出将闭包参数另起一行的写法，我认为更合理，解决了多个闭包参数过长的问题。

对于一行表达式闭包，当使用场景明确时，可以使用隐式返回：

attendeeList.sort {
        a, b in
      a > b
    }

### 类型 ###

请尽量使用Swift提供的原生类型。Swift也提供了原生类型对象桥接到`Objective-C`对象的办法，所以必要时你能随意使用这些桥接对象提供的方法。

推荐：

let width = 120.0                                           //Double
    let widthString = width.bridgeToObjectiveC().stringValue    //String

不推荐：

let width: NSNumber = 120.0                                 //NSNumber
    let widthString: NSString = width.stringValue               //NSString

在`Sprite Kit`代码中，请多使用`CGFloat`，这样代码会更简洁，也能避免非常多的类型转换。

#### 常量 ####

常量使用`let`关键字定义，而变量使用`var`关键字定义。

如果一个值是常量，那就必须使用`let`关键字来准确定义。最终你会发现，你使用`let`的频率远大于`var`。

> 小技巧：一开始你可以将所有值都定义为常量，然后如果编译器报错了再作适当的调整。

#### 可选 ####

如果可以接受`nil`值，请将变量或函数返回值的类型定义为可选类型（加`?`）。

当你明确知道实例变量在使用前会完成初始化，比如说视图控制器中的子视图`subviews`在使用前会在`viewDidLoad`中初始化，那么你可以将这些变量定义为隐式解析类型（使用`!`）。

当访问一个可选值时，如果只访问一次，或者方式时有多种可能性，请使用可选链：

myOptional?.anotherOne?.optionalView?.setNeedsDisplay()

使用可选绑定`optional binding`对只拆包（`unwrap`）一次，但执行多次操作的情况非常合适：

if let view = self.optionalView {
       
      // do many things with view
    }

#### 类型推断 ####

Swift编译器可以推断出变量和常量的类型。你可以为每个常量或变量提供一个显示的类型（加个冒号，并在后面写上类型名），但大部分情况不必这么做。

我们建议多使用类型推断让编译器自动推断出常量或变量的类型，这样代码会更紧凑。

推荐：

let message = "Click the button"
    var currentBounds = computeViewBounds()

不推荐：

let message: String = "Click the button"
    var currentBounds: CGRect = computeViewBounds()

> 注意：遵循此规则意味着在命名时，需要更慎重的选择具有描述性的名字。

### 流程控制 ###

建议多使用`for-in`风格的`for`循环，而不是传统的`for-condition-increment`风格。

推荐：

for _ in 0..5 {
       
      println("Hello five times")
    }
    
    for person in attendeeList {
       
      // do something
    }

不推荐：

for var i = 0; i < 5; i++ {
       
      println("Hello five times")
    }
    
    for var i = 0; i < attendeeList.count; i++ {
       
      let person = attendeeList[i]
      // do something
    }

### 笑脸 ###

笑脸在raywenderlich.com网站中是一个非常突出的特性。正确的使用笑脸来表达在编程时的一种极大的快乐和兴奋，至关重要。我们使用右方括号`]`，因为它代表了`ASCII`艺术字符中最大的微笑；而使用右小括号`)`的笑脸显得有点不那么诚心，所以我们不推荐使用。

推荐：

不推荐：

[1405122209554]: http://www.tairan.com/wp-content/uploads/2014/12/1405122209554.jpg
[The Official raywenderlich.com Swift Style Guide]: https://github.com/raywenderlich/swift-style-guide
[ObjC]: https://github.com/raywenderlich/objective-c-style-guide
[Link 1]: http://stackoverflow.com/questions/444080/do-you-recommend-using-semicolons-after-every-statement-in-javascript
[aemaeth]: https://swiftist.org/~aemaeth