您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發基礎

Swift 團隊代碼規範指南:從命名約定到內存管理的完整實踐

編輯:iOS 開發基礎

投稿文章,作者:南栀傾寒(博客)

工作節奏終於穩定下來,公司也正式啟動了代碼規範統一與組件化改造。由於團隊裡 Objective-C 的開發者佔了大多數,架構師先梳理了一套 Objective-C 的編碼約定;而我作為 Swift 方向的老司機,也順手整理了一份面向 Swift 的規範,之後可以直接複用。

好的規範不是為了束縛,而是為了讓團隊在協作時擁有一致的表達方式。以下按「註釋 → 命名 → 格式 → 類型 → 可選值 → 類與結構體 → 閉包 → 內存與訪問控制」的順序展開。

一、註釋與文檔

基礎註釋

// 單行註釋
/* 多行註釋 */
/// 文檔註釋(單行)
/** 文檔註釋(多行) */

強烈建議安裝 VVDocument-Xcode 這類插件,讓文檔註釋的撰寫變成一次回車的事。

文檔註釋支持 Markdown

以 /** 包裹即可,不必在每一行開頭都補上星號。註釋內容支持完整的 Markdown 語法,可以寫標題、列表、示例代碼和注意事項:

/**
## 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 {
    /* ... */
}

方法註釋

用 - parameter、- warning 等標記說明參數與風險點,Xcode 會自動在自動補全提示中呈現這些信息:

/**
This does something with a `UIViewController`, perchance.

- warning: Make sure that `someValue` is `true`
  before running this function.
*/
func myFunction() {
    /* ... */
}

二、命名約定

統一採用可讀性優先的駝峰命名法。類型(class、struct、protocol、enum)首字母大寫,變量與成員首字母小寫。

private let maximumWidgetCount = 100

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

全局函數與初始化方法建議為每個參數提供外部標籤,調用點的語義才會清晰:

func dateFromString(dateString: String) -> Date
func convertPointAt(column column: Int, row: Int) -> CGPoint
func timedAction(afterDelay delay: TimeInterval, perform action: SKAction) -> SKAction

// 調用時的可讀性
dateFromString("2014-03-14")
convertPointAt(column: 42, row: 13)
timedAction(afterDelay: 1.0, perform: someOtherAction)

協議(Protocol)命名

遵循 Apple API Design Guidelines,用名詞描述能力,常見後綴為 -ing、-able、-ible:

Collection
WidgetFactory
Equatable
Resizing

枚舉(Enum)命名

每個 case 使用小寫駝峰:

enum Shape {
    case rectangle
    case square
    case rightTriangle
    case equilateralTriangle
}

類型前綴

Swift 自帶命名空間,官方並不鼓勵添加前綴。但現實項目裡難免引入開源庫(多數通過 Pods 管理),偶爾需要直接改源碼並把文件放進工程,加上混編場景大量存在,命名衝突的風險並不低。此時保留一個統一前綴(例如 LJ)是務實的選擇。

class LJHomeViewController: UIViewController {}

Selector 選擇器

優先在可推斷的上下文裡寫簡短形式,而不是依賴 Xcode 的 Fix-it 生成全名稱:

// 推薦
let sel = #selector(viewDidLoad)

// 不推薦
let sel = #selector(ViewController.viewDidLoad)

泛型

泛型參數同樣使用大駝峰。如果確實沒有語義化的合適名稱,用 T、U、V 這類約定俗成的字母即可。

// 推薦
struct Stack { /* ... */ }
func writeTo(target: inout Target)
func max(x: T, _ y: T) -> T

// 不推薦
struct Stack { /* ... */ }              // 命名無意義
func writeTo(inout t: target)           // 首字母未大寫
func max(x: Thing, _ y: Thing) -> Thing  // 簡稱即可

三、代碼格式

空白的使用

  • 使用 Tab 縮進,不要用空格堆疊。
  • 文件末尾保留一個空行。
  • 用足夠的空行把代碼切成合理的邏輯塊,而不是擠成一團。
  • 行尾不留多餘空格,空行裡也不要有殘留的縮進。

冒號緊跟標識符

聲明類型時,冒號跟在變量名後面,然後空一格再寫類型:

class SmallBatchSustainableFairtrade: Coffee { /* ... */ }

let timeToCoffee: TimeInterval = 2

func makeCoffee(type: CoffeeType) -> Coffee {
    /* ... */
}

控制流

優先使用 Swift 風格的 for-in,告別 C 式 for 與 while:

for _ in 0..<3 {
    print("Hello three times")
}

for (index, person) in attendeeList.enumerated() {
    print("\(person) is at position #\(index)")
}

for index in stride(from: 0, to: items.count, by: 2) {
    print(index)
}

for index in (0...3).reversed() {   // 3, 2, 1, 0
    print(index)
}

代碼塊縮進

if / else / switch / while 以及函數的大括號留在當行行尾,前面保留一個空格;能省的括號就不要寫。

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

// 不推薦:多餘括號、括號換行位置錯誤
if (user.isHappy)
{
    // Do something
}
else {
    // Do something else
}

提前返回(Early Return)

需要條件守衛時,採用防禦式編程盡早退出,避免層層嵌套。guard 的語義就是「確保」:

guard n.isNumber else {
    return
}

guard let number1 = number1, number2 = number2, number3 = number3 else {
    fatalError("impossible")
}
// 這裡可以安心使用 number1、number2、number3

// 不推薦:嵌套 if 讓可讀性急劇下降
if n.isNumber {
    // Use n here
} else {
    return
}

分號

不寫分號,不寫分號,不寫分號。Swift 不同於 JavaScript,語句之間不需要分號分隔,更不建議把多條語句塞進同一行。

自定義運算符

運算符左右各留一個空格,避免與一元運算符混淆:

// 重構前
func <- (lhs: Int, rhs: Int) -> Int
func <|< (lhs: A, rhs: A) -> A

// 重構後
func <-> (lhs: Int, rhs: Int) -> Int
func <|> (lhs: A, rhs: A) -> A

用 MARK 做代碼分割

// MARK: -     類似 Objective-C 的 #pragma mark -
// MARK:       不帶分隔線的分組標記

協議實現分離

一個類型實現多個協議時,建議用 extension 拆開,讓職責邊界一目了然:

class MyViewController: UIViewController {
    // class stuff here
}

// MARK: - UITableViewDataSource
extension MyViewController: UITableViewDataSource {
    // table view data source methods
}

// MARK: - UIScrollViewDelegate
extension MyViewController: UIScrollViewDelegate {
    // scroll view delegate methods
}

// 不推薦:所有協議方法堆在一起
class MyViewController: UIViewController, UITableViewDataSource, UIScrollViewDelegate {
    // all methods
}

刪掉無用代碼

廢棄的代碼和過期註釋要果斷刪除。留著只會讓後來接手的人反覆猜測:這段是不是還有用途?

四、類型與變量

盡量直接使用 Swift 原生類型,只有在必須與系統 API 交互時才做橋接(String 與 NSString、Set 與 NSSet)。

更重要的是:多用 let,少用 var。let 本身就是一份可靠的聲明——值不會變,同事讀到這裡就知道後續可以放心推斷,不必再人工排查。反過來,一旦寫下 var,讀代碼的人就必須時刻懸著「它會不會被改」這個問題。養成習慣:看到 var 就默認它會變,並主動找出變化發生的位置與原因。

常量

不要直接定義頂層變量,把它們放進 struct 或 enum 裡用 static let 聲明,順帶獲得一個天然的命名空間:

enum Math {
    static let e = 2.718281828459045235360287
    static let pi = 3.141592653589793238462643
}

let circumference = radius * Math.pi * 2

五、可選值(Optional)

盡量少用強制解包。對於 let foo: Type?,不要寫 foo!.doSomething(),改用可選綁定或可選鏈:

if let foo = foo {
    // 使用解包後的 foo
} else {
    // 按需處理 foo 為 nil 的情況
}

// 或者:foo 不為 nil 時調用,為 nil 時靜默跳過
foo?.callSomethingIfFooIsNotNil()

同時避免隱式解包可選類型。如果 foo 可能為 nil,用 let foo: FooType? 而不是 let foo: FooType!——絕大多數情況下問號都能替代感嘆號。

結構體初始化器

用結構體初始化方法代替 CGGet 系列函數:

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

延遲加載

開銷較大或配置步驟繁多的初始化,適合交給 lazy:

lazy var locationManager: CLLocationManager = self.makeLocationManager()

private func makeLocationManager() -> CLLocationManager {
    let manager = CLLocationManager()
    manager.desiredAccuracy = kCLLocationAccuracyBest
    manager.delegate = self
    manager.requestAlwaysAuthorization()
    return manager
}

六、類與結構體

優先選 struct

在沒有生命週期需求的前提下優先使用 struct:多態可以靠 protocol 實現,代碼復用可以靠組合完成。值類型語義清晰,配合 let 還能直接表達不可變意圖。

只在必要時寫 self

不必糾結 Objective-C 時代 self.prop 與 _ivar 的選擇,Swift 內部訪問属性和方法時直接省略 self:

private class History {
    var events: [Event]

    func rewrite() {
        events = []
    }
}

只有兩種情況需要顯式寫上 self:閉包內(此時 self 明確表達了「捕獲」的語義),以及與參數命名衝突時。

extension History {
    init(events: [Event]) {
        self.events = events
    }

    var whenVictorious: () -> () {
        return {
            self.rewrite()
        }
    }
}

只讀屬性使用隱式 getter

// 推薦
var myGreatProperty: Int {
    return 4
}

subscript(index: Int) -> T {
    return objects[index]
}

// 不推薦:冗餘的 get 塊
var myGreatProperty: Int {
    get {
        return 4
    }
}

默認把 class 標記為 final

組合通常比繼承更合適,而 final 能免除動態派發的開銷,也迫使設計者在繼承前想清楚:

// 用這個 Box 類把任意泛型類型變成引用類型
final class Box {
    let value: T

    init(_ value: T) {
        self.value = value
    }
}

類型推斷

系統能推斷的類型就不要顯式標註:

// 重構前
struct Composite {
    func compose(other: Composite) -> Composite {
        return Composite(self, other)
    }
}
let num: Int = 4

// 重構後
let num = 4

但空字典與空數組是例外,此時類型標記能起到強化語義的作用:

var names: [String] = []
var lookup: [String: Int] = [:]

七、函數與閉包

函數聲明

函數名簡短清晰。簽名能放一行就保持一行,實在太長再換行並用縮進對齊:

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

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

閉包表達式

用尾隨閉包提升可讀性:

UIView.animate(withDuration: 1.0) {
    self.myView.alpha = 0
}

UIView.animate(withDuration: 1.0,
               animations: {
                   self.myView.alpha = 0
               },
               completion: { finished in
                   self.myView.removeFromSuperview()
               })

語義明確的簡短閉包可以使用縮寫參數,鏈式調用時每個環節換行對齊:

let value = numbers.map { $0 * 2 }.filter { $0 % 3 == 0 }.index(of: 90)

let value = numbers
    .map { $0 * 2 }
    .filter { $0 > 50 }
    .map { $0 + 10 }

語法糖

有語法糖就用語法糖:

// 推薦
var deviceModels: [String]
var employees: [Int: String]
var faxNumber: Int?

// 不推薦
var deviceModels: Array
var employees: Dictionary
var faxNumber: Optional

八、內存管理與訪問控制

引用類型必須關注內存管理。普通閉包建議使用 [weak self] 或 [unowned self];異步閉包則推薦 [weak self] 搭配 guard let strongSelf = self else { return }——weak 用來斷開循環引用,strongSelf 用來避免異步回調期間捕獲的對象被提前釋放。

resource.request().onComplete { [weak self] response in
    guard let strongSelf = self else { return }

    let model = strongSelf.updateModel(response)
    strongSelf.updateUI(model)
}

最後,頂層類型、函數與變量都應顯式標註訪問級別,讓模塊邊界清晰可見:

public var whoopsGlobalState: Int

internal struct TheFez {}

private func doTheThings(things: [Thing]) {}

結語

規範的價值在於長期積累的一致性:命名統一了,搜索和閱讀成本就下降;格式統一了,代碼審查的注意力才能集中在邏輯本身;可選值與內存處理統一了,線上崩潰和內存洩露的概率就會顯著降低。建議把這份約定接入 SwiftLint 等工具自動化執行,讓人只負責判斷,機器負責約束。

參考來源

Github、LinkedIn、Prolific Interactive、RayWenderlich

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved