raywenderlich.com的Swift编程风格指南

翻译自：https://github.com/raywenderlich/swift-style-guide

这个风格指南可能和你从其它地方看到的不同，我们的焦点主要集中在互联网和文章上的可读性。创建这个编程风格指南是为了保持我们的书籍、教程和入门工具包中代码的优雅与一致性------虽然我们有和很多不同的作者合作。

我们的首要目的是简洁、可读性和简单。

你在写Objective-C吗？看看我们的Objective-C风格指南吧。

文件夹

命名

对类、方法、变量等使用包括描写叙述性的驼峰式（CamelCase）命名。类名和全局常量的全部首字母大写，方法和变量名開始第一个字母小写。

建议：

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)

对于方法而言。依照Apple的习惯，在方法名里引用第一个參数：

class Guideline {

  func combineWithString(incoming: String, options: Dictionary?) { ... }

  func upvoteBy(amount: Int) { ... }

}

当我们在文章中须要引用方法的地方，要从调用者的角度包括全部必须的參数名。假设上下文非常清晰。并且准确的方法签名不重要时。你就能仅仅用法名。

从你自己的init方法实现中调用convertPointAt(column:row:)。

假设你实现了didSelectRowAtIndexPath，那么记得在你完毕工作后取消选择行。

你不能直接调用dataSource的tableView(_:cellForRowAtIndexPath:) 。

类前缀

Swift的类型都自己主动的有其模块的命名空间，其结果是不用为了降低名称冲突而必须使用前缀。假设有两个来自于不同模块的名称起了冲突，你能够通过在类型名称前加上模块名来消除两者间的歧义：

import MyModule

var myClass = MyModule.MyClass()

你不应该为Swift类型加上前缀。

假设你须要暴露一个Swift类型在Objective-C里使用，你也能提供一个合适的前缀，就像以下这样：

@objc (RWTChicken) class Chicken {

   ...

}

间隔

使用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

}

在方法之间应该正好有一个空行。这能使结构看起来更加清晰。

在方法内用空行分隔功能。但假设分隔成太多段的话，经常意味着你须要把一个方法重构成多个方法。

凝视

在须要的时候。用凝视来解释一段特殊的代码为什么要这么做，凝视必须保持更新或者干脆删掉。

避免在代码里嵌入大块凝视，应该让代码本身作为自己的文档。

例外：这不适用于那些通过凝视来生成文档的情况。

类和结构体

这里有一个风格非常好的定义类的样例：

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 \(centerString()) with an area of \(computeArea())"

  }

  override func computeArea() -> Double {

    return M_PI * radius * radius

  }

  private func centerString() -> String {

    return "(\(x),\(y))"

  }

}

上面的这个样例清晰地展示了以下规则：

为属性、变量、常量、參数定义以及其它申明指定类型的时候，在冒号后面而不是前面添加一个空格，比方：x: Int 和 Circle: Shape。
对于多个变量，假设它们有相同的结构和上下文环境（比方x、y），则把它们定义在同一行。
缩进属性（property）的getter/setter定义。
不要加入像interal这种默认修饰符。相同的，当覆盖一个方法时。不要在方法上再次写上它的訪问修饰符。

Self的使用

避免使用self。由于Swift并不须要使用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

}

闭包

尽可能地使用跟随闭包语法（Trailing Closure Syntax）。

在不论什么情况下，给闭包中的參数具有描写叙述性的名称：

return SKAction.customActionWithDuration(effect.duration) { node, elapsedTime in

  // more code goes here

}

对上下文清晰的单行表达式闭包，使用隐式的return：

attendeeList.sort { a, b in

  a > b

}

类型

假设可能的话，总是使用Swift的原生类型。

Swift提供了桥接（Bridging）到Objective-C的功能，在须要时你也能使用Objective-C的完整方法：

建议：

let width = 120.0                                    //Double

let widthString = (width as NSNumber).stringValue    //String

不建议：

let width: NSNumber = 120.0                                 //NSNumber

let widthString: NSString = width.stringValue               //NSString

在使用Sprite Kit的代码里，使用CGFloat能使代码更加简洁，同一时候能避免太多的类型转换。

常量

常量使用letkeyword定义，变量使用varkeyword定义。用let适当地定义那些永远不会被改动的值。你可能会因此发现你自己用let远超过用var。

提示：一个技巧能帮助我们达到这个标准：把全部的东西都定义成常量，仅仅有当编译器报错时才将其替换为变量。

Optional

用?定义变量和方法的返回值为optional。表示该值能够接受nil。

假设你知道一个实例变量一定会在使用前被初始化，如viewDidLoad方法里会设置全部的子视图，你就能用 ! 对这个变量做隐式的拆包。

当訪问一个optional的值时，假设该值仅仅訪问一次，或者有太多的optioanl值关联。那么就用Optional Chaining：

myOptional?

.anotherOne?.optionalView?.setNeedsDisplay()

假设想更方便的做一次拆包然后运行多个操作。用Optional Binding：

if let view = self.optionalView {

  // do many things with view

}

结构体的初始化

使用Swift原生的结构体初始化方式比曾经的CGGeometry构造方式要好。

建议：

let bounds = CGRect(x: 40, y: 20, width: 120, height: 80)

var centerPoint = CGPoint(x: 96, y: 42)

不建议：

let bounds = CGRectMake(40, 20, 120, 80)

var centerPoint = CGPointMake(96, 42)

类型判断

Swift编译器能够判断出变量和常量的数据类型。你能够通过提供类型别名（就是冒号后面的）来显式声明数据类型。但大多数情况下不须要这么做。

我们喜欢简明扼要的代码。让编译器去判断变量和常量的类型吧。

（在某些情况下可能须要显式声明，比方你对一个变量赋一个浮点型，Swift会将这个变量判断为double。而不是float，假设你一定要用float，就仅仅能显式声明了）

建议：

let message = "Click the button"

var currentBounds = computeViewBounds()

不建议：

let message: String = "Click the button"

var currentBounds: CGRect = computeViewBounds()

备注：依照本原则：取一个具有描写叙述性的名字比什么都要重要。

语法糖

定义泛型类型时使用快捷方式比使用完整语法要更好。

建议：

var deviceModels: [String]

var employees: [Int: String]

var faxNumber: Int?

不建议：

var deviceModels: Array<String>

var employees: Dictionary<Int, String>

var faxNumber: Optional<Int>

控制流

for-in比完整的for-condition-increment样式要好：

建议：

for _ in 0..<3 {

  println("Hello three times")

}

for person in attendeeList {

  // do something

}

不建议：

for var i = 0; i < 3; i++ {

  println("Hello three times")

}

for var i = 0; i < attendeeList.count; i++ {

  let person = attendeeList[i]

  // do something

}

分号

Swift不再须要你的每一行代码后面加上分号，仅仅要当你想把多条语句放在同一行的时候才是必须的。

不要把多条语句用分号分隔写在一行。

仅仅有一种例外情况：构造for-condition-increment的时候必须用分号。然而，尽可能地使用for-in循环。

建议：

var swift = "not a scripting language"

不建议：

var swift = "not a scripting language";

备注：Swift与JavaScript有非常大不同，在JavaScript里省略分号通常被觉得是不安全的。

语言

使用美式英语去适应Apple的API。

建议：

var color = "red"

不建议：

var colour = "red"

笑脸

笑脸是raywenderlick.com站点非常突出的特色功能。正确的笑脸意味着对编程有着无比的快乐与兴奋。这是非常重要的。使用右方括号]代表了能被ASCII Art记录的最大的微笑。而右括号）表示创建了一个半心半意的笑脸，因此这是不可取的。

建议：

:]

不建议：

:)

功臣

这份风格指南是最时尚的raywenderlich.com团队成员们努力协作的成果：

Soheil Moayedi Azarpour
Scott Berrevoets
Eric Cerney
Sam Davies
Evan Dekhayser
Jean-Pierre Distler
Colin Eberhardt
Greg Heo
Matthijs Hollemans
Erik Kerber
Christopher LaPollo
Andy Pereira
Ryan Nystrom
Cesare Rocchi
Ellen Shapiro
Marin Todorov
Chris Wagner
Ray Wenderlich
Jack Wu

向Nicholas Waynik和Objective-C风格指南的团队致敬！

我们的灵感来自于苹果的Swift參考材料：

巴特西

raywenderlich.com的Swift编程风格指南

文件夹

命名

建议：

不建议：

类前缀

间隔

建议：

不建议：

凝视

类和结构体

Self的使用

函数定义

闭包

类型

建议：

不建议：

常量

Optional

结构体的初始化

建议：

不建议：

类型判断

建议：

不建议：

语法糖

建议：

不建议：

控制流

建议：

不建议：

分号

建议：

不建议：

语言

建议：

不建议：

笑脸

建议：

不建议：

功臣

最新文章

热门文章