来自Linkedin的Swift编程风格指南 LinkedIn Swift Style Guide

分享到:  QQ好友和群QQ好友和群 QQ空间QQ空间 腾讯微博腾讯微博 腾讯朋友腾讯朋友 微信微信
查看查看179 回复回复2 收藏收藏1 分享淘帖 转播转播 分享分享1 微信
查看: 179|回复: 2
收起左侧

来自Linkedin的Swift编程风格指南 LinkedIn Swift Style Guide

[复制链接]
cocoaswift 发表于 2016-7-1 14:34:07 | 显示全部楼层 |阅读模式
快来登录
获取优质的苹果资讯内容
收藏热门的iOS等技术干货
拷贝下载Swift Demo源代码
订阅梳理好了的知识点专辑

首先推荐阅读下:Apple's API Design Guidelines




0、目录 Table Of Contents

1. Code Formatting

2. Naming

3. Coding Style

  • 3.1 General
  • 3.2 Access Modifiers
  • 3.3 Custom Operators
  • 3.4 Switch Statements and enums
  • 3.5 Optionals
  • 3.6 Protocols
  • 3.7 Properties
  • 3.8 Closures
  • 3.9 Arrays
  • 3.10 Error Handling
  • 3.11 Using guard Statements


4. Documentation/Comments

  • 4.1 Documentation
  • 4.2 Other Commenting Guidelines



来自Linkedin的Swift编程风格指南 LinkedIn Swift Style Guide

来自Linkedin的Swift编程风格指南 LinkedIn Swift Style Guide - 敏捷大拇指 - 来自Linkedin的Swift编程风格指南 LinkedIn Swift Style Guide





1、Code Formatting 代码格式化

1.1 使用4个空格来代替Tabs

1.2 避免过长的行,可以在XCode中进行设置单行最大长度:(Xcode->Preferences->Text Editing->Page guide at column: 160 is helpful for this)

1.3 保证每个文件结尾都存在一个新行 Ensure that there is a newline at the end of every file.

1.4 避免无意义的尾随空格: (Xcode->Preferences->Text Editing->Automatically trim trailing whitespace + Including whitespace-only lines).

1.5 避免将单独的左花括号放置到一行,我们参考了:1TBS style

[Swift] 纯文本查看 复制代码
class SomeClass {
    func someMethod() {
        if x == y {
            /* ... */
        } else if x == z {
            /* ... */
        } else {
            /* ... */
        }
    }
    /* ... */
}


1.6 在写变量的类型声明、字典类型的键、函数参数、协议的声明或者父类的时候,不要在冒号前添加空格。

[Swift] 纯文本查看 复制代码
// specifying type
let pirateViewController: PirateViewController
// dictionary syntax (note that we left-align as opposed to aligning colons)
let ninjaDictionary: [String: AnyObject] = [
    "fightLikeDairyFarmer": false,
    "disgusting": true
]
// declaring a function
func myFunction<t, u: someprotocol where t.relatedtype == u>(firstArgument: U, secondArgument: T) {
    /* ... */
}
// calling a function
someFunction(someArgument: "Kitten")
// superclasses
class PirateViewController: UIViewController {
    /* ... */
}
// protocols
extension PirateViewController: UITableViewDataSource {
    /* ... */
}</t, u: someprotocol where t.relatedtype == u>


1.7 一般来说,逗号后面都要跟随一个空格。

[Swift] 纯文本查看 复制代码
let myArray = [1, 2, 3, 4, 5]


1.8 在二元操作符譬如+, ==, 或者 ->的前后需要加上空格,但是对于( 、`)的前后不需要加空格。

[Swift] 纯文本查看 复制代码
let myValue = 20 + (30 / 2) * 3
if 1 + 1 == 3 {
    fatalError("The universe is broken.")
}
func pancake() -> Pancake {
    /* ... */
}


1.9 我们默认使用Xcode推荐的格式化风格(CTRL-I),在声明某个函数的时候会多行排布参数。

[Swift] 纯文本查看 复制代码
// Xcode indentation for a function declaration that spans multiple lines
func myFunctionWithManyParameters(parameterOne: String,
                                  parameterTwo: String,
                                  parameterThree: String) {
    // Xcode indents to here for this kind of statement
    print("\(parameterOne) \(parameterTwo) \(parameterThree)")
}
// Xcode indentation for a multi-line `if` statement
if myFirstVariable > (mySecondVariable + myThirdVariable)
    && myFourthVariable == .SomeEnumValue {
    // Xcode indents to here for this kind of statement
    print("Hello, World!")
}


1.10 在调用多参数函数的时候,会把多个参数放置到单独的行中:

[Swift] 纯文本查看 复制代码
someFunctionWithManyArguments(
    firstArgument: "Hello, I am a string",
    secondArgument: resultFromSomeFunction()
    thirdArgument: someOtherLocalVariable)


1.11 对于大型的数组或者字典类型,应该将其分割到多行内,[ 与 ]类比于花括号进行处理。对于闭包而言也应该同样适合于该规则。

[Swift] 纯文本查看 复制代码
someFunctionWithABunchOfArguments(
    someStringArgument: "hello I am a string",
    someArrayArgument: [
        "dadada daaaa daaaa dadada daaaa daaaa dadada daaaa daaaa",
        "string one is crazy - what is it thinking?"
    ],
    someDictionaryArgument: [
        "dictionary key 1": "some value 1, but also some more text here",
        "dictionary key 2": "some value 2"
    ],
    someClosure: { parameter1 in
        print(parameter1)
    })


1.12 尽可能地使用本地变量的方式来避免多行的判断语句。

[Swift] 纯文本查看 复制代码
// PREFERRED
let firstCondition = x == firstReallyReallyLongPredicateFunction()
let secondCondition = y == secondReallyReallyLongPredicateFunction()
let thirdCondition = z == thirdReallyReallyLongPredicateFunction()
if firstCondition && secondCondition && thirdCondition {
    // do something
}
// NOT PREFERRED
if x == firstReallyReallyLongPredicateFunction()
    && y == secondReallyReallyLongPredicateFunction()
    && z == thirdReallyReallyLongPredicateFunction() {
    // do something
}





2、Naming 命名

2.1 Swift中不需要再使用Objective-C那样的前缀,譬如使用 GuybrushThreepwood 而不是LIGuybrushThreepwood。

2.2 对于类型名即struct, enum, class, typedef, associatedtype等等使用 PascalCase 。

2.3 对于函数名、方法名、变量名、常量、参数名等使用camelCase。

2.4 在使用首字母缩写的时候尽可能地全部大写,并且注意保证全部代码中的统一。不过如果缩写被用于命名的起始,那么就全部小写。

[Swift] 纯文本查看 复制代码
// "HTML" is at the start of a variable name, so we use lowercase "html"
let htmlBodyContent: String = "<p>Hello, World!</p>"
// Prefer using ID to Id
let profileID: Int = 1
// Prefer URLFinder to UrlFinder
class URLFinder {
    /* ... */
}


2.5 对于静态常量使用 k 前缀 + PascalCase。

[Swift] 纯文本查看 复制代码
class MyClassName {
    // use `k` prefix for constant primitives
    static let kSomeConstantHeight: CGFloat = 80.0
    // use `k` prefix for non-primitives as well
    static let kDeleteButtonColor = UIColor.redColor()
    // don't use `k` prefix for singletons
    static let sharedInstance = MyClassName()
    /* ... */
}


2.6 对于泛型或者关联类型,使用PascalCase描述泛型,如果泛型名与其他重复,那么可以添加一个Type后缀名到泛型名上。

[Swift] 纯文本查看 复制代码
class SomeClass<t> { /* ... */ }
class SomeClass<model> { /* ... */ }
protocol Modelable {
    associatedtype Model
}
protocol Sequence {
    associatedtype IteratorType: Iterator
}</model></t>


2.7 命名必须要是不模糊的并且方便表述的。

[Swift] 纯文本查看 复制代码
// PREFERRED
class RoundAnimatingButton: UIButton { /* ... */ }
// NOT PREFERRED
class CustomButton: UIButton { /* ... */ }


2.8 不要使用缩写,可以选择较为简短的单词。

[Swift] 纯文本查看 复制代码
// PREFERRED
class RoundAnimatingButton: UIButton {
    let animationDuration: NSTimeInterval
    func startAnimating() {
        let firstSubview = subviews.first
    }
}
// NOT PREFERRED
class RoundAnimating: UIButton {
    let aniDur: NSTimeInterval
    func srtAnmating() {
        let v = subviews.first
    }
}


2.9 对于不是很明显的类型需要将类型信息包含在属性名中。

[Swift] 纯文本查看 复制代码
// PREFERRED
class ConnectionTableViewCell: UITableViewCell {
    let personImageView: UIImageView
    let animationDuration: NSTimeInterval
    // it is ok not to include string in the ivar name here because it's obvious
    // that it's a string from the property name
    let firstName: String
    // though not preferred, it is OK to use `Controller` instead of `ViewController`
    let popupController: UIViewController
    let popupViewController: UIViewController
    // when working with a subclass of `UIViewController` such as a table view
    // controller, collection view controller, split view controller, etc.,
    // fully indicate the type in the name.
    let popupTableViewController: UITableViewController
    // when working with outlets, make sure to specify the outlet type in the
    // variable name.
    @IBOutlet weak var submitButton: UIButton!
    @IBOutlet weak var emailTextField: UITextField!
    @IBOutlet weak var nameLabel: UILabel!
}
// NOT PREFERRED
class ConnectionTableViewCell: UITableViewCell {
    // this isn't a `UIImage`, so shouldn't be called image
    // use personImageView instead
    let personImage: UIImageView
    // this isn't a `String`, so it should be `textLabel`
    let text: UILabel
    // `animation` is not clearly a time interval
    // use `animationDuration` or `animationTimeInterval` instead
    let animation: NSTimeInterval
    // this is not obviously a `String`
    // use `transitionText` or `transitionString` instead
    let transition: String
    // this is a view controller - not a view
    let popupView: UIViewController
    // as mentioned previously, we don't want to use abbreviations, so don't use
    // `VC` instead of `ViewController`
    let popupVC: UIViewController
    // even though this is still technically a `UIViewController`, this variable
    // should indicate that we are working with a *Table* View Controller
    let popupViewController: UITableViewController
    // for the sake of consistency, we should put the type name at the end of the
    // variable name and not at the start
    @IBOutlet weak var btnSubmit: UIButton!
    @IBOutlet weak var buttonSubmit: UIButton!
    // we should always have a type in the variable name when dealing with outlets
    // for example, here, we should have `firstNameLabel` instead
    @IBOutlet weak var firstName: UILabel!
}


2.10 在编写函数参数的时候,要保证每个参数都易于理解其功能。

2.11 根据 Apple's API Design Guidelines, 对于protocol,如果其描述的是正在做的事情,譬如Collection,那么应该命名为名词。而如果是用于描述某种能力,譬如Equatable, ProgressReporting,那么应该添加 able, ible, 或者 ing 这样的后缀。如果你的协议并不符合上述两种情形,那么应该直接添加一个Protocol后缀,譬如:

[Swift] 纯文本查看 复制代码
// here, the name is a noun that describes what the protocol does
protocol TableViewSectionProvider {
    func rowHeight(atRow row: Int) -> CGFloat
    var numberOfRows: Int { get }
    /* ... */
}
// here, the protocol is a capability, and we name it appropriately
protocol Loggable {
    func logCurrentState()
    /* ... */
}
// suppose we have an `InputTextView` class, but we also want a protocol
// to generalize some of the functionality - it might be appropriate to
// use the `Protocol` suffix here
protocol InputTextViewProtocol {
    func sendTrackingEvent()
    func inputText() -> String
    /* ... */
}





3、Coding Style 编程风格


3.1、General

3.1.1 尽可能地使用let来代替var。

3.1.2 尽可能地使用 map, filter, reduce的组合来进行集合的转换等操作,并且尽可能地避免使用带有副作用的闭包。

[Swift] 纯文本查看 复制代码
// PREFERRED
let stringOfInts = [1, 2, 3].flatMap { String($0) }
// ["1", "2", "3"]
// NOT PREFERRED
var stringOfInts: [String] = []
for integer in [1, 2, 3] {
    stringOfInts.append(String(integer))
}
// PREFERRED
let evenNumbers = [4, 8, 15, 16, 23, 42].filter { $0 % 2 == 0 }
// [4, 8, 16, 42]
// NOT PREFERRED
var evenNumbers: [Int] = []
for integer in [4, 8, 15, 16, 23, 42] {
    if integer % 2 == 0 {
        evenNumbers(integer)
    }
}


3.1.3 尽可能地显式声明不方便进行类型推测的变量或者常量的类型名。

3.1.4 如果你的函数需要返回多个参数,那么尽可能地使用Tuple来代替inout参数。如果你会多次使用某个元组,那么应该使用typealias设置别名。如果返回的参数超过三个,那么应该使用结构体或者类来替代。

[Swift] 纯文本查看 复制代码
func pirateName() -> (firstName: String, lastName: String) {
    return ("Guybrush", "Threepwood")
}
let name = pirateName()
let firstName = name.firstName
let lastName = name.lastName


3.1.5 在创建delegates/protocols的时候需要小心所谓的保留环(retain cycles),这些属性需要被声明为weak。

3.1.6 在闭包中直接调用self可能会导致保留环,可以使用capture list 在这种情况下:

[Swift] 纯文本查看 复制代码
myFunctionWithClosure() { [weak self] (error) -> Void in
    // you can do this
    self?.doSomething()
    // or you can do this
    guard let strongSelf = self else {
        return
    }
    strongSelf.doSomething()
}


3.1.7 不要使用 labeled breaks。

3.1.8 不要在控制流逻辑判断的时候加上圆括号。

[Swift] 纯文本查看 复制代码
// PREFERRED
if x == y {
    /* ... */
}
// NOT PREFERRED
if (x == y) {
    /* ... */
}


3.1.9 避免在使用enum的时候写出全名。

[Swift] 纯文本查看 复制代码
// PREFERRED
imageView.setImageWithURL(url, type: .person)
// NOT PREFERRED
imageView.setImageWithURL(url, type: AsyncImageView.Type.person)


3.1.10 在写类方法的时候不能用简短写法,应该使用类名.方法名,这样能够保证代码的可读性。

[Swift] 纯文本查看 复制代码
// PREFERRED
imageView.backgroundColor = UIColor.whiteColor()
// NOT PREFERRED
imageView.backgroundColor = .whiteColor()


3.1.11 在非必要的时候不要写self.。

3.1.12 在编写某个方法的时候注意考虑下这个方法是否有可能被复写,如果不可能被复写那么应该使用final修饰符。还要注意加上final之后也会导致无法在测试的时候进行复写,所以还是需要综合考虑。一般而言,加上final修饰符后会提高编译的效率,所以应该尽可能地使用该修饰符。

3.1.13 在使用譬如else, catch等等类似的语句的时候,将关键字与花括号放在一行,同样遵循1TBS style规范,这边列出了常见的if/else 以及 do/catch 示范代码。

[Swift] 纯文本查看 复制代码
if someBoolean {
    // do something
} else {
    // do something else
}
do {
    let fileContents = try readFile("filename.txt")
} catch {
    print(error)
}



3.2、Access Modifiers

3.2.1 在需要的时候应该将访问修饰符放在关键字的第一位。

[Swift] 纯文本查看 复制代码
// PREFERRED
private static let kMyPrivateNumber: Int
// NOT PREFERRED
static private let kMyPrivateNumber: Int


3.2.2 访问修饰符不应该单独放一行:

[Swift] 纯文本查看 复制代码
// PREFERRED
public class Pirate {
    /* ... */
}
// NOT PREFERRED
public
class Pirate {
    /* ... */
}


3.2.3 一般来说,不要显式地写默认的 internal访问修饰符。

3.2.4 如果某个变量需要在测试的时候被使用到,那么应该标识为internal来保证@testable import ModuleName。这里需要注意的是,对于某些应该被声明为private的变量因为测试用途而声明为了internal,那么应该在注释里特别地注明。

[Swift] 纯文本查看 复制代码
/**
 This variable defines the pirate's name.
 - warning: Not `private` for `@testable`.
 */
let pirateName = "LeChuck"



3.3、Custom Operators 自定义操作符

尽可能地选用命名函数来代替自定义操作符。如果你打算引入一个自定义的操作符,那么一定要有非常充分的理由来说明为啥要讲一个新的操作符引入到全局作用域,而不是使用其他一些可替代的方式。你也可以选择去复写一些现有的操作符,譬如==来适应一些新的类型,不过要保证你添加的用法一定要与语义相符。譬如== 应该只能用于表示相等性测试并且返回一个布尔值。


3.4、Switch Statements and enums

3.4.1 在使用枚举类型作为switch的参数的时候,避免引入default关键字,而应该将没有使用的情形放到下面然后使用break关键字来避免被执行。

3.4.2 Swift中默认会在每个case的结尾进行break,因此没必要的时候不需要显式地声明break关键字。

3.4.3 The case statements should line up with the switch statement itself as per default Swift standards.

3.4.4 When defining a case that has an associated value, make sure that this value is appropriately labeled as opposed to just types (e.g. case Hunger(hungerLevel: Int) instead of case Hunger(Int)).

[Swift] 纯文本查看 复制代码
enum Problem {
    case attitude
    case hair
    case hunger(hungerLevel: Int)
}
func handleProblem(problem: Problem) {
    switch problem {
    case .attitude:
        print("At least I don't have a hair problem.")
    case .hair:
        print("Your barber didn't know when to stop.")
    case .hunger(let hungerLevel):
        print("The hunger level is \(hungerLevel).")
    }
}


3.4.5 优先使用譬如 case 1, 2, 3: 这样的列表表达式而不是使用fallthrough关键字。

3.4.6 如果你添加了一个默认的case并且该case不应该被使用,那么应该在default情形下抛出异常。

[Swift] 纯文本查看 复制代码
func handleDigit(digit: Int) throws {
    case 0, 1, 2, 3, 4, 5, 6, 7, 8, 9:
        print("Yes, \(digit) is a digit!")
    default:
        throw Error(message: "The given number was not a digit.")
}



3.5、Optionals

3.5.1 只应该在 @IBOutlet中使用隐式地未包裹的Options。否则其他情况下就应该使用Non-Optional或者正常的Optional的变量。虽然有时候你能保证某个变量肯定非nil,不过这样用的话还是比较安全并且能保证上下一致性。

The only time you should be using implicitly unwrapped optionals is withs. In every other case, it is better to use a non-optional or regular optional variable. Yes, there are cases in which you can probably "guarantee" that the variable will never be nil when used, but it is better to be safe and consistent.

3.5.2 不要使用 as! 或者 try! 。

3.5.3 如果你只是打算判断存放在Optional中的值是否为空,那么你应该直接与nil进行判断而不是使用if let语句将值取出来。

[Swift] 纯文本查看 复制代码
// PREFERERED
if someOptional != nil {
    // do something
}
// NOT PREFERRED
if let _ = someOptional {
    // do something
}


3.5.4 不要使用 unowned。你可以将unowned当做对于weak变量的隐式解包,虽然有时候unowned与weak相比有小小地性能提升,不过还是不建议进行使用。

[Swift] 纯文本查看 复制代码
// PREFERRED
weak var parentViewController: UIViewController?
// NOT PREFERRED
weak var parentViewController: UIViewController!
unowned var parentViewController: UIViewController


3.5.5 当对Optionals进行解包的时候,使用与Optionals变量一致的变量名。

[Swift] 纯文本查看 复制代码
guard let myVariable = myVariable else {
    return
}



3.6、Protocols

在实现协议的时候,大体上有两种代码组织方式:

  • 使用 // MARK: 来注释你的专门用于实现协议中规定的方法
  • 在你的类或者结构体实现之外使用一个扩展来存放实现代码,不过要保证在一个源文件中


不过需要注意的是,如果你是使用了Extension方式,那么定义在Extension中的方法是无法被子类复写的,这样可能会无法进行测试。



3.7、Properties

3.7.1 如果是定义一个只读的需要经过计算的属性,那么不需要声明 get {}

[Swift] 纯文本查看 复制代码
var computedProperty: String {
    if someBool {
        return "I'm a mighty pirate!"
    }
    return "I'm selling these fine leather jackets."
}


3.7.2 在使用 get {}, set {}, willSet, 以及 didSet,注意块的缩进

3.7.3 尽管你可以在willSet/didSet以及 set方法中使用自定义的名称,不过建议还是使用默认的newValue/oldValue 变量名

[Swift] 纯文本查看 复制代码
var computedProperty: String {
    get {
        if someBool {
            return "I'm a mighty pirate!"
        }
        return "I'm selling these fine leather jackets."
    }
    set {
        computedProperty = newValue
    }
    willSet {
        print("will set to \(newValue)")
    }
    didSet {
        print("did set from \(oldValue) to \(newValue)")
    }
}


3.7.4 将任何类常量设置为static

[Swift] 纯文本查看 复制代码
class MyTableViewCell: UITableViewCell {
    static let kReuseIdentifier = String(MyTableViewCell)
    static let kCellHeight: CGFloat = 80.0
}


3.7.5 可以使用如下方式便捷地声明一个单例变量:

[Swift] 纯文本查看 复制代码
class PirateManager {
    static let sharedInstance = PirateManager()
    /* ... */
}



3.8、Closures:闭包

3.8.1 如果闭包中的某个参数的类型是显而易见的,那么可以避免声明类型。不过有时候为了保证可读性与一致性,还是会显示声明参数类型。

[Swift] 纯文本查看 复制代码
// omitting the type
doSomethingWithClosure() { response in
    print(response)
}
// explicit type
doSomethingWithClosure() { response: NSURLResponse in
    print(response)
}
// using shorthand in a map statement
[1, 2, 3].flatMap { String($0) }


3.8.2 在参数列表中,如果是使用了捕获变量或者声明了非Void的返回值,那么应该将参数列表写在一个圆括号里,其他情况下则可以省略圆括号。

[Swift] 纯文本查看 复制代码
// parentheses due to capture list
doSomethingWithClosure() { [weak self] (response: NSURLResponse) in
    self?.handleResponse(response)
}
// parentheses due to return type
doSomethingWithClosure() { (response: NSURLResponse) -> String in
    return String(response)
}


3.8.3 如果你是将闭包声明为一个类型,那么除非该类型为Optional或者该闭包是另一个闭包的参数,否则不需要使用圆括号进行包裹。不过需要用圆括号来标注参数列表,并且使用Void来指明没有任何结果返回。

[Swift] 纯文本查看 复制代码
let completionBlock: (success: Bool) -> Void = {
    print("Success? \(success)")
}
let completionBlock: () -> Void = {
    print("Completed!")
}
let completionBlock: (() -> Void)? = nil


3.8.4 尽可能地将参数名与左括号放在一行,不过要避免打破每行最长160个字符的限制。

Keep parameter names on same line as the opening brace for closures when possible without too much horizontal overflow (i.e. ensure lines are less than 160 characters).

3.8.5 尽可能地使用 trailing closure表达式,除非需要显示地声明闭包参数的外部参数名。

[Swift] 纯文本查看 复制代码
// trailing closure
doSomething(1.0) { parameter1 in
    print("Parameter 1 is \(parameter1)")
}
// no trailing closure
doSomething(1.0, success: { parameter1 in
    print("Success with \(parameter1)")
}, failure: { parameter1 in
    print("Failure with \(parameter1)")
})



3.9、Arrays

3.9.1 一般来说,避免使用下标直接访问某个数组,而应该使用类似于.first、.last这样的访问器进行访问。另外,应该优先使用for item in items语法来替代for i in 0..

3.9.2 永远不要使用+= 或者 +运算符来增加或者连接数组,应该使用.append() 或者 .appendContentsOf() 方法。如果你想定义一个从其他数组生成的不可变数组,那么应该使用let关键字,即: let myNewArray = arr1 + arr2, 或者 let myNewArray = [arr1, arr2].flatten()。


3.10、Error Handling

假设某个函数 myFunction 需要去返回一个String类型,不过有可能会在某个点抛出异常,一般来说会将该函数的返回值设置为String?:

Example:

[Swift] 纯文本查看 复制代码
func readFile(withFilename filename: String) -> String? {
    guard let file = openFile(filename) else {
        return nil
    }
    let fileContents = file.read()
    file.close()
    return fileContents
}
func printSomeFile() {
    let filename = "somefile.txt"
    guard let fileContents = readFile(filename) else {
        print("Unable to open file \(filename).")
        return
    }
    print(fileContents)
}


不过作为异常处理的角度,我们应该使用Swift的try-catch表达式,这样能显式地知道错误点:

[Swift] 纯文本查看 复制代码
struct Error: ErrorType {
    public let file: StaticString
    public let function: StaticString
    public let line: UInt
    public let message: String
    public init(message: String, file: StaticString = #file, function: StaticString = #function, line: UInt = #line) {
        self.file = file
        self.function = function
        self.line = line
        self.message = message
    }
}


Example usage:

[Swift] 纯文本查看 复制代码
func readFile(withFilename filename: String) throws -> String {
    guard let file = openFile(filename) else {
        throw Error(message: "Unable to open file named \(filename).")
    }
    let fileContents = file.read()
    file.close()
    return fileContents
}
func printSomeFile() {
    do {
        let fileContents = try readFile(filename)
        print(fileContents)
    } catch {
        print(error)
    }
}


总而言之,如果某个函数可能会出错,并且出错的原因不能显式地观测到,那么应该优先抛出异常而不是使用一个Optional作为返回值。


3.11、Using guard Statements

3.11.1 一般来说,我们会优先使用所谓的"early return"策略来避免if表达式中的多层嵌套的代码。在这种情况下使用guard语句能够有效地提升代码的可读性。

[Swift] 纯文本查看 复制代码
// PREFERRED
func eatDoughnut(atIndex index: Int) {
    guard index >= 0 && index < doughnuts else {
        // return early because the index is out of bounds
        return
    }
    let doughnut = doughnuts[index]
    eat(doughnut)
}
// NOT PREFERRED
func eatDoughnuts(atIndex index: Int) {
    if index >= 0 && index < donuts.count {
        let doughnut = doughnuts[index]
        eat(doughnut)
    }
}


3.11.2 在对Optional类型进行解包的时候,优先使用 guard 语句来避免if语句中较多的缩进。

[Swift] 纯文本查看 复制代码
// PREFERRED
guard let monkeyIsland = monkeyIsland else {
    return
}
bookVacation(onIsland: monkeyIsland)
bragAboutVacation(onIsland: monkeyIsland)
// NOT PREFERRED
if let monkeyIsland = monkeyIsland {
    bookVacation(onIsland: monkeyIsland)
    bragAboutVacation(onIsland: monkeyIsland)
}
// EVEN LESS PREFERRED
if monkeyIsland == nil {
    return
}
bookVacation(onIsland: monkeyIsland!)
bragAboutVacation(onIsland: monkeyIsland!)


3.11.3 在决定是要用if表达式还是guard表达式进行Optional类型解包的时候,最重要的点就是要保证代码的可读性。很多时候要注意因时而变,因地制宜:

[Swift] 纯文本查看 复制代码
// an `if` statement is readable here
if operationFailed {
    return
}
// a `guard` statement is readable here
guard isSuccessful else {
    return
}
// double negative logic like this can get hard to read - i.e. don't do this
guard !operationFailed else {
    return
}


3.11.4 当需要进行多可能性处理的时候,应该优先使用if表达式而不是guard表达式。

[Swift] 纯文本查看 复制代码
// PREFERRED
if isFriendly {
    print("Hello, nice to meet you!")
} else {
    print("You have the manners of a beggar.")
}
// NOT PREFERRED
guard isFriendly else {
    print("You have the manners of a beggar.")
    return
}
print("Hello, nice to meet you!")


3.11.5 一般来说,guard应该被用于需要直接退出当前上下文的情形。而对于下面这种两个条件互不干扰的情况,应该使用两个if而不是两个guard。

[Swift] 纯文本查看 复制代码
if let monkeyIsland = monkeyIsland {
    bookVacation(onIsland: monkeyIsland)
}
if let woodchuck = woodchuck where canChuckWood(woodchuck) {
    woodchuck.chuckWood()
}


3.11.6 有时候我们会碰到要用guard语句进行多个optionals解包的情况,一般而言,对于复杂的错误处理的Optional类型需要将其拆分到多个单个表达式中。

[Swift] 纯文本查看 复制代码
// combined because we just return
guard let thingOne = thingOne,
    let thingTwo = thingTwo,
    let thingThree = thingThree else {
    return
}
// separate statements because we handle a specific error in each case
guard let thingOne = thingOne else {
    throw Error(message: "Unwrapping thingOne failed.")
}
guard let thingTwo = thingTwo else {
    throw Error(message: "Unwrapping thingTwo failed.")
}
guard let thingThree = thingThree else {
    throw Error(message: "Unwrapping thingThree failed.")
}


3.11.7 不要将guard表达式强行缩写到一行内。

[Swift] 纯文本查看 复制代码
// PREFERRED
guard let thingOne = thingOne else {
    return
}
// NOT PREFERRED
guard let thingOne = thingOne else { return }





4、Documentation/Comments



4.1、Documentation

如果某个函数不是简单地O(1)操作,那么最好就是为该函数添加一些注释文档,这样能有效地提高代码的可读性与可维护性。之前有个非常不错的文档工具VVDocumenter。推荐阅读Apple的官方指南中的描述:described in Apple's Documentation

Guidelines:

4.1.1 每行不应超过160个字符

4.1.2 即使某些注释只有一行,也应该使用块注释符: (/** */).

4.1.3 不用给每行的开头都加上: *.

4.1.4 使用新的 - parameter 标识符来代替老的

[Swift] 纯文本查看 复制代码
:param: syntax


(注意这边是小写的 parameter 而不是Parameter)。

4.1.5 如果你准备对参数/返回值/异常值来写注释,那么注意要一个不落的全局加上,尽管有时候会让文档显得重复冗余。有时候,如果只需要对单个参数进行注释,那么还不如直接放在描述里进行声明,而不需要专门的为参数写一个注释。

4.1.6 对于复杂的使用类,应该添加一些具体的使用用例来描述类的用法。注意Swift的注释文档中是支持MarkDown语法的,这是一个很好的特性。

[Swift] 纯文本查看 复制代码
/**
 ## Feature Support
 This class does some awesome things. It supports:
 - Feature 1
 - Feature 2
 - Feature 3
 ## Examples
 Here is an example use case indented by four spaces because that indicates a
 code block:
     let myAwesomeThing = MyAwesomeClass()
     myAwesomeThing.makeMoney()
 ## Warnings:告警
 There are some things you should be careful of:
 1. Thing one
 2. Thing two
 3. Thing three
 */
class MyAwesomeClass {
    /* ... */
}


4.1.7 使用 - ` 在注释中著名引用的代码

[Swift] 纯文本查看 复制代码
/**
 This does something with a `UIViewController`, perchance.
 - warning: Make sure that `someValue` is `true` before running this function.
 */
func myFunction() {
    /* ... */
}


4.1.8 保证文档的注释尽可能的简洁



4.2、Other Commenting Guidelines 其他的注释规则

4.2.1 //后面总是要跟上一个空格

4.2.2 注释永远要放在单独的行中

4.2.3 在使用// MARK: - whatever的时候,注意MARK与代码之间保留一个空行

[Swift] 纯文本查看 复制代码
class Pirate {
    // MARK: - instance properties
    private let pirateName: String
    // MARK: - initialization
    init() {
        /* ... */
    }
}





原文:Swift Style Guide
译者:王下邀月熊_Chevalier(Github

都看到这里了,就把这篇资料推荐给您的好朋友吧,让他们也感受一下。

回帖是一种美德,也是对楼主发帖的尊重和支持。

*声明:敏捷大拇指是全球最大的Swift开发者社区、苹果粉丝家园、智能移动门户,所载内容仅限于传递更多最新信息,并不意味赞同其观点或证实其描述;内容仅供参考,并非绝对正确的建议。本站不对上述信息的真实性、合法性、完整性做出保证;转载请注明来源并加上本站链接,敏捷大拇指将保留所有法律权益。如有疑问或建议,邮件至marketing@swifthumb.com

*联系:微信公众平台:“swifthumb” / 腾讯微博:@swifthumb / 新浪微博:@swifthumb / 官方QQ一群:343549891(满) / 官方QQ二群:245285613 ,需要报上用户名才会被同意进群,请先注册敏捷大拇指

嗯,不错!期待更多好内容,支持一把:
支持敏捷大拇指,用支付宝支付10.24元 支持敏捷大拇指,用微信支付10.24元

评分

参与人数 1金钱 +10 贡献 +10 专家分 +10 收起 理由
Anewczs + 10 + 10 + 10 32个赞!专家给力!

查看全部评分

瑶池 发表于 2016-7-2 16:00:58 | 显示全部楼层
必须收藏!
 楼主| cocoaswift 发表于 2016-7-5 19:15:03 | 显示全部楼层

谢谢美女的认可!
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

做任务,领红包。
我要发帖

分享扩散

都看到这里了,就把这资料推荐给您的好朋友吧,让他们也感受一下。
您的每一位朋友访问此永久链接后,您都将获得相应的金钱积分奖励
关闭

站长推荐 上一条 /3 下一条

热门推荐

合作伙伴

Swift小苹果

  • 北京治世天下科技有限公司
  • ©2014-2016 敏捷大拇指
  • 京ICP备14029482号
  • Powered by Discuz! X3.1 Licensed
  • swifthumb Wechat Code
  •   
快速回复 返回顶部 返回列表