
投稿文章,作者:南栀傾寒(博客)
工作節奏終於穩定下來,公司也正式啟動了代碼規範統一與組件化改造。由於團隊裡 Objective-C 的開發者佔了大多數,架構師先梳理了一套 Objective-C 的編碼約定;而我作為 Swift 方向的老司機,也順手整理了一份面向 Swift 的規範,之後可以直接複用。
好的規範不是為了束縛,而是為了讓團隊在協作時擁有一致的表達方式。以下按「註釋 → 命名 → 格式 → 類型 → 可選值 → 類與結構體 → 閉包 → 內存與訪問控制」的順序展開。
// 單行註釋 /* 多行註釋 */ /// 文檔註釋(單行) /** 文檔註釋(多行) */
強烈建議安裝 VVDocument-Xcode 這類插件,讓文檔註釋的撰寫變成一次回車的事。
以 /** 包裹即可,不必在每一行開頭都補上星號。註釋內容支持完整的 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)
遵循 Apple API Design Guidelines,用名詞描述能力,常見後綴為 -ing、-able、-ible:
Collection WidgetFactory Equatable Resizing
每個 case 使用小寫駝峰:
enum Shape {
case rectangle
case square
case rightTriangle
case equilateralTriangle
}
Swift 自帶命名空間,官方並不鼓勵添加前綴。但現實項目裡難免引入開源庫(多數通過 Pods 管理),偶爾需要直接改源碼並把文件放進工程,加上混編場景大量存在,命名衝突的風險並不低。此時保留一個統一前綴(例如 LJ)是務實的選擇。
class LJHomeViewController: UIViewController {}
優先在可推斷的上下文裡寫簡短形式,而不是依賴 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 // 簡稱即可
聲明類型時,冒號跟在變量名後面,然後空一格再寫類型:
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
}
需要條件守衛時,採用防禦式編程盡早退出,避免層層嵌套。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: - 類似 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
盡量少用強制解包。對於 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:多態可以靠 protocol 實現,代碼復用可以靠組合完成。值類型語義清晰,配合 let 還能直接表達不可變意圖。
不必糾結 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()
}
}
}
// 推薦
var myGreatProperty: Int {
return 4
}
subscript(index: Int) -> T {
return objects[index]
}
// 不推薦:冗餘的 get 塊
var myGreatProperty: Int {
get {
return 4
}
}
組合通常比繼承更合適,而 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