Swift

Swift公司项目开发规范

2017-09-15  本文已影响73人  小奉不在乎

前言

注：本文档借鉴与多个文档整理而成，如观看时引起你的不适，我深表抱歉！

关于Swift的代码的相关规范，不同的开发者都有自己相应的规范，可能还是很多人根本就没有规范。为了保证同一个公司同一个项目组中代码美观并且一致，这里写下这份我们公司的Swift编程规范指南。该指南首要目标是让代码紧凑，可读性更高且简洁。当然不一定适用于所有公司。

APP版本号规范

以三位数版本号控制                                --> 0.0.1

Bug修复递增最后一位                               --> 0.0.2

新增功能递增第二位重置第三位为0                     --> 0.1.0

bug修复及新增递增第二位,重置第三位为0               --> 0.2.0

重大更新及bug修复递增第一位，第二位,第三位 重置为0     --> 1.0.0

版本号递增规则上不封顶(以当前使用的 Mac 系统版本为例)  -->10.12.6

代码规范

Xcode->Preferences->Text Editing->Page guide at column

let array = [1, 2, 3, 4, 5];

let value = 20 + (34 / 2) * 3
if 1 + 1 == 2 {
    //TODO
}
func pancake -> Pancake {
    /** do something **/
}


class SomeClass {
    func someMethod() {
        if x == y {
            /* ... */
        } else if x == z {
            /* ... */
        } else {
            /* ... */
        }
    }
    /* ... */
}

// Xcode针对跨多行函数声明缩进
func myFunctionWithManyParameters(parameterOne: String,
                                  parameterTwo: String,
                                  parameterThree: String) {
    // Xcode会自动缩进
    print("\(parameterOne) \(parameterTwo) \(parameterThree)")
}
// Xcode针对多行 if 语句的缩进
if myFirstVariable > (mySecondVariable + myThirdVariable)
    && myFourthVariable == .SomeEnumValue {
    // Xcode会自动缩进
    print("Hello, World!")
}

functionWithArguments(
    firstArgument: "Hello, I am a string",
    secondArgument: resultFromSomeFunction()
    thirdArgument: someOtherLocalVariable)

functionWithBunchOfArguments(
    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)
})

// 推荐
let firstCondition = x == firstReallyReallyLongPredicateFunction()
let secondCondition = y == secondReallyReallyLongPredicateFunction()
let thirdCondition = z == thirdReallyReallyLongPredicateFunction()
if firstCondition && secondCondition && thirdCondition {
    // 你要干什么
}
// 不推荐
if x == firstReallyReallyLongPredicateFunction()
    && y == secondReallyReallyLongPredicateFunction()
    && z == thirdReallyReallyLongPredicateFunction() {
    // 你要干什么
}

命名

// "HTML" 是变量名的开头, 需要全部小写 "html"
let htmlBodyContent: String = "<p>Hello, World!</p>"
// 推荐使用 ID 而不是 Id
let profileID: Int = 1
// 推荐使用 URLFinder 而不是 UrlFinder
class URLFinder {
    /* ... */
}

class ClassName {
    // 基元常量使用 k 作为前缀
    static let kSomeConstantHeight: CGFloat = 80.0
    // 非基元常量也是用 k 作为前缀
    static let kDeleteButtonColor = UIColor.redColor()
    // 对于单例不要使用k作为前缀
    static let sharedInstance = MyClassName()
    /* ... */
}

// 推荐
class RoundAnimatingButton: UIButton { /* ... */ }
// 不推荐
class CustomButton: UIButton { /* ... */ }

// 推荐
class RoundAnimatingButton: UIButton {
    let animationDuration: NSTimeInterval
    func startAnimating() {
        let firstSubview = subviews.first
    }
}
// 不推荐
class RoundAnimating: UIButton {
    let aniDur: NSTimeInterval
    func srtAnmating() {
        let v = subviews.first
    }
}

// 推荐
class ConnectionTableViewCell: UITableViewCell {

    let personImageView: UIImageView

    let animationDuration: NSTimeInterval
    // 作为属性名的firstName，很明显是字符串类型，所以不用在命名里不用包含String
    let firstName: String
    // 虽然不推荐, 这里用 Controller 代替 ViewController 也可以。
    let popupController: UIViewController
    let popupViewController: UIViewController
    // 如果需要使用UIViewController的子类，如TableViewController, CollectionViewController, SplitViewController, 等，需要在命名里标名类型。
    let popupTableViewController: UITableViewController
    // 当使用outlets时, 确保命名中标注类型。
    @IBOutlet weak var submitButton: UIButton!
    
    @IBOutlet weak var emailTextField: UITextField!
    // 没有注释的前面空出一行
    @IBOutlet weak var nameLabel: UILabel!
    // 多个组合单词建议使用"_"进行区分
    @IBOutlet weak var create_timeLabel: UILabel!
    // 不需要外部使用的属性记得加上private修饰
    private let edgeMargin : CGFloat = 62
}
// 不推荐
class ConnectionTableViewCell: UITableViewCell {
    // 这个不是 UIImage, 不应该以Image 为结尾命名。
    // 建议使用 personImageView
    let personImage: UIImageView
    // 这个不是String，应该命名为 textLabel
    let text: UILabel
    // animation 不能清晰表达出时间间隔
    // 建议使用 animationDuration 或 animationTimeInterval
    let animation: NSTimeInterval
    // transition 不能清晰表达出是String
    // 建议使用 transitionText 或 transitionString
    let transition: String
    // 这个是ViewController，不是View
    let popupView: UIViewController
    // 由于不建议使用缩写，这里建议使用 ViewController替换 VC
    let popupVC: UIViewController
    // 技术上讲这个变量是 UIViewController, 但应该表达出这个变量是TableViewController
    let popupViewController: UITableViewController
    // 为了保持一致性，建议把类型放到变量的结尾，而不是开始，如submitButton
    @IBOutlet weak var btnSubmit: UIButton!
    @IBOutlet weak var buttonSubmit: UIButton!
    // 在使用outlets 时，变量名内应包含类型名。
    // 这里建议使用 firstNameLabel
    @IBOutlet weak var firstName: UILabel!
}

当给函数参数命名时，要确保函数能够理解每个参数的目的。

代码风格

综合
// 推荐
let stringOfInts = [1, 2, 3].flatMap { String($0) }
// ["1", "2", "3"]
// 不推荐
var stringOfInts: [String] = []
for integer in [1, 2, 3] {
    stringOfInts.append(String(integer))
}

// 推荐
let evenNumbers = [4, 8, 15, 16, 23, 42].filter { $0 % 2 == 0 }
// [4, 8, 16, 42]
// 不推荐
var evenNumbers: [Int] = []
for integer in [4, 8, 15, 16, 23, 42] {
    if integer % 2 == 0 {
        evenNumbers(integer)
    }
}

func pirateName() -> (firstName: String, lastName: String) {
    return ("Guybrush", "Threepwood")
}
let name = pirateName()
let firstName = name.firstName
let lastName = name.lastName

functionWithClosure() { [weak self] (error) -> Void in
    // 方案 1
    self?.doSomething()
    // 或方案 2
    guard let strongSelf = self else {
        return
    }
    strongSelf.doSomething()
}

// 推荐
if x == y {
    /* ... */
}
// 不推荐
if (x == y) {
    /* ... */
}

// 推荐
imageView.setImageWithURL(url, type: .person)
// 不推荐
imageView.setImageWithURL(url, type: AsyncImageView.Type.person)

// 推荐
imageView.backgroundColor = UIColor.whiteColor()
// 不推荐
imageView.backgroundColor = .whiteColor()

if someBoolean {
    // 你想要什么
} else {
    // 你不想做什么
}
do {
    let fileContents = try readFile("filename.txt")
} catch {
    print(error)
}
访问控制修饰符
// 推荐
private static let kMyPrivateNumber: Int
// 不推荐
static private let kMyPrivateNumber: Int

// 推荐
public class Pirate {
    /* ... */
}
// 不推荐
public
class Pirate {
    /* ... */
}

/**
 这个变量是private 名字
 - warning: 定义为 internal 而不是 private 为了 `@testable`.
 */
let pirateName = "LeChuck"
自定义操作符
switch语句和枚举
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).")
    }
}

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.")
}

可选类型

// 推荐
if nil != someOptional {
    // 你要做什么
}
// 不推荐
if let _ = someOptional {
    // 你要做什么
}

// 推荐
weak var parentViewController: UIViewController?
// 不推荐
weak var parentViewController: UIViewController!
unowned var parentViewController: UIViewController

guard let myVariable = myVariable else {
    return
}

协议

在实现协议的时候，有两种方式来组织你的代码：

var computedProperty: String {
    if someBool {
        return "I'm a mighty pirate!"
    }
    return "I'm selling these fine leather jackets."
}

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)")
    }
}

class MyTableViewCell: UITableViewCell {
    static let kReuseIdentifier = String(MyTableViewCell)
    static let kCellHeight: CGFloat = 80.0
}

class PirateManager {
    static let sharedInstance = PirateManager()
    /* ... */
}

闭包

如果参数的类型很明显，可以在函数名里可以省略参数类型, 但明确声明类型也是允许的。 代码的可读性有时候是添加详细的信息，而有时候部分重复，根据你的判断力做出选择吧，但前后要保持一致性。

// 省略类型
doSomethingWithClosure() { response in
    print(response)
}
// 明确指出类型
doSomethingWithClosure() { response: NSURLResponse in
    print(response)
}
// map 语句使用简写
[1, 2, 3].flatMap { String($0) }

// 因为使用捕捉列表，小括号不能省略。
doSomethingWithClosure() { [weak self] (response: NSURLResponse) in
    self?.handleResponse(response)
}
// 因为返回类型，小括号不能省略。
doSomethingWithClosure() { (response: NSURLResponse) -> String in
    return String(response)
}

let completionBlock: (success: Bool) -> Void = {
    print("Success? \(success)")
}
let completionBlock: () -> Void = {
    print("Completed!")
}
let completionBlock: (() -> Void)? = nil
数组
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("不能打开 \(filename).")
        return
    }
    print(fileContents)
}

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
    }
}

func readFile(withFilename filename: String) throws -> String {
    guard let file = openFile(filename) else {
        throw Error(message: “打不开的文件名称 \(filename).")
    }
    let fileContents = file.read()
    file.close()
    return fileContents
}
func printSomeFile() {
    do {
        let fileContents = try readFile(filename)
        print(fileContents)
    } catch {
        print(error)
    }
}

// 推荐
func eatDoughnut(atIndex index: Int) {
    guard index >= 0 && index < doughnuts else {
        // 如果 index 超出允许范围，提前返回。
        return
    }
    let doughnut = doughnuts[index]
    eat(doughnut)
}
// 不推荐
func eatDoughnuts(atIndex index: Int) {
    if index >= 0 && index < donuts.count {
        let doughnut = doughnuts[index]
        eat(doughnut)
    }
}

// 推荐
guard let monkeyIsland = monkeyIsland else {
    return
}
bookVacation(onIsland: monkeyIsland)
bragAboutVacation(onIsland: monkeyIsland)
// 不推荐
if let monkeyIsland = monkeyIsland {
    bookVacation(onIsland: monkeyIsland)
    bragAboutVacation(onIsland: monkeyIsland)
}
// 禁止
if monkeyIsland == nil {
    return
}
bookVacation(onIsland: monkeyIsland!)
bragAboutVacation(onIsland: monkeyIsland!)

// if 语句更有可读性
if operationFailed {
    return
}
// guard 语句这里有更好的可读性
guard isSuccessful else {
    return
}
// 双重否定不易被理解 - 不要这么做
guard !operationFailed else {
    return
}

// 推荐
if isFriendly {
    print("你好, 远路来的朋友！")
} else {
    print(“穷小子，哪儿来的？")
}
// 不推荐
guard isFriendly else {
    print("穷小子，哪儿来的？")
    return
}
print("你好, 远路来的朋友！")

if let monkeyIsland = monkeyIsland {
    bookVacation(onIsland: monkeyIsland)
}
if let woodchuck = woodchuck where canChuckWood(woodchuck) {
    woodchuck.chuckWood()
}

// 组合在一起因为可能立即返回
guard let thingOne = thingOne,
    let thingTwo = thingTwo,
    let thingThree = thingThree else {
        return
}
// 使用独立的语句 因为每个场景返回不同的错误
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.")
}

文档/注释

/**
 ## 功能列表
 这个类提供下一下很赞的功能，如下:
 - 功能 1
 - 功能 2
 - 功能 3
 ## 例子
 这是一个代码块使用四个空格作为缩进的例子。
 let myAwesomeThing = MyAwesomeClass()
 myAwesomeThing.makeMoney()
 ## 警告
 使用的时候总注意以下几点
 1. 第一点
 2. 第二点
 3. 第三点
 */
class MyAwesomeClass {
    /* ... */
}

在写文档注释时，尽量保持简洁。

class Pirate {
    // MARK: - 实例属性
    
    private let pirateName: String
    // MARK: - 初始化
    
    init() {
        /* ... */
    }
}
上一篇 下一篇

猜你喜欢

热点阅读