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能使代码更加简洁，同时能避免太多的类型转换。

常量

常量使用let关键字定义，变量使用var关键字定义。用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参考材料：

时间： 2024-04-20 08:10:13

raywenderlich.com的Swift编程风格指南的相关文章

Google C++编程风格指南（八）：规则之例外

编程风格指南的使用要点在于提供一个公共的编码规范,所有人可以把精力集中在实现内容而不是表现形式上.我们给出了全局的风格规范,但局部的风格也很重要,如果你在一个文件中新加的代码和原有代码风格相去甚远的话,这就破坏了文件本身的整体美观也影响阅读 规则之例外 前面说明的编码习惯基本是强制性的,但所有优秀的规则都允许例外. 1. 现有不统一代码(Existing Non-conformant Code) 对于现有不符合既定编程风格的代码可以网开一面. 当你修改使用其他风格的代码时,为了与代码原有风格保持

Google Java 编程风格指南

前言 这份文档是Google Java编程风格规范的完整定义.当且仅当一个Java源文件符合此文档中的规则, 我们才认为它符合Google的Java编程风格. 与其它的编程风格指南一样,这里所讨论的不仅仅是编码格式美不美观的问题, 同时也讨论一些约定及编码标准.然而,这份文档主要侧重于我们所普遍遵循的规则, 对于那些不是明确强制要求的,我们尽量避免提供意见. 1.1 术语说明 在本文档中,除非另有说明: 术语class可表示一个普通类,枚举类,接口或是annotation类型(@interfac

Google Java编程风格指南

作者:Hawstein出处:http://hawstein.com/posts/google-java-style.html声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|Creative Commons BY-NC-ND 3.0 ,转载请注明作者及出处. 目录 前言 源文件基础 源文件结构 格式 命名约定 编程实践 Javadoc 后记 前言 这份文档是Google Java编程风格规范的完整定义.当且仅当一个Java源文件符合此文档中的规则, 我们才认为它符合Googl

Google C++编程风格指南（一）

背景 Google的开源项目大多使用C++开发.每一个C++程序员也都知道,C++具有很多强大的语言特性,但这种强大不可避免的导致它的复杂,这种复杂会使得代码更易于出现bug.难于阅读和维护. 本指南的目的是通过详细阐述在C++编码时要怎样写.不要怎样写来规避其复杂性.这些规则可在允许代码有效使用C++语言特性的同时使其易于管理. 风格,也被视为可读性,主要指称管理C++代码的习惯.使用术语风格有点用词不当,因为这些习惯远不止源代码文件格式这么简单. 使代码易于管理的方法之一是增强代码一致性,让

Google Python编程风格指南

背景 Python 是 Google主要的脚本语言.这本风格指南主要包含的是针对python的编程准则. 为帮助读者能够将代码准确格式化,我们提供了针对 Vim的配置文件 .对于Emacs用户,保持默认设置即可. Python语言规范 Lint 对你的代码运行pylint 定义: pylint是一个在Python源代码中查找bug的工具. 对于C和C++这样的不那么动态的(译者注: 原文是less dynamic)语言, 这些bug通常由编译器来捕获. 由于Python的动态特性, 有些警告可能

Google C++编程风格指南（七）：格式

1.行宽原则上不超过80列,把22寸的显示屏都占完,怎么也说不过去:2.尽量不使用非ASCII字符:3.UNIX/Linux下无条件使用空格,MSVC的话使用Tab也无可厚非:4.函数参数.逻辑条件.初始化列表:要么所有参数和函数名放在同一行,要么所有参数并排分行-- 格式 代码风格和格式确实比较随意,但一个项目中所有人遵循同一风格是非常容易的,作为个人未必同意下述格式规则的每一处,但整个项目服从统一的编程风格是很重要的,这样做才能让所有人在阅读和理解代码时更加容易. 1.行长度(Line Le

JavaScript编程风格指南

介绍 作者根据Robert C. Martin<代码整洁之道>总结了适用于JavaScript的软件工程原则<Clean Code JavaScript>. 本文是对其的翻译. 不必严格遵守本文的所有原则,有时少遵守一些效果可能会更好,具体应根据实际情况决定.这是根据<代码整洁之道>作者多年经验整理的代码优化建议,但也仅仅只是一份建议. 软件工程已经发展了50多年,至今仍在不断前进.现在,把这些原则当作试金石,尝试将他们作为团队代码质量考核的标准之一吧. 最后你需要知道

Google C++编程风格指南（六）：代码注释

注释 注释虽然写起来很痛苦,但对保证代码可读性至为重要,下面的规则描述了应该注释什么.注释在哪儿.当然也要记住,注释的确很重要,但最好的代码本身就是文档(self-documenting),类型和变量命名意义明确要比通过注释解释模糊的命名好得多. 注释是为别人(下一个需要理解你的代码的人)而写的,认真点吧,那下一个人可能就是你! 1.注释风格(Comment Style) 使用//或/* */,统一就好. //或/* */都可以,//只是用的更加广泛,在如何注释和注释风格上确保统一. 2.文件注

Google C++编程风格指南（五）：命名约定

1.总体规则:不要随意缩写:2.宏.枚举等使用全部大写+下划线:3.变量(含类.结构体成员变量).文件.命名空间.存取函数等使用全部小写+下划线,类成员变量以下划线结尾,全局变量以g_开头:4.参考现有或相近命名约定-- 命名约定 最重要的一致性规则是命名管理,命名风格直接可以直接确定命名实体是:类型.变量.函数.常量.宏等等,无需查找实体声明,我们大脑中的模式匹配引擎依赖于这些命名规则. 命名规则具有一定随意性,但相比按个人喜好命名,一致性更重要,所以不管你怎么想,规则总归是规则. 1.通用命