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

Objective-C 編碼規範:讓團隊代碼風格統一的 26 條準則

編輯:iOS 開發綜合

每個人寫 Objective-C 的習慣都不一樣,風格一亂,代碼一致性與 Code Review 的效率就跟著下降。為了讓專案代碼保持優雅、一致且易讀,參與開發的所有人都應該盡量遵守同一套風格指南。以下即為本專案的編碼規範,若有更好的做法,歡迎隨時提出優化。

1. 語言

變數、方法與註解一律使用美式英語拼寫。

2. 代碼組織

用 #pragma mark - 為方法分組,並遵循大致固定的順序:生命週期 → 自訂 setter/getter → 公開方法 → 私有方法。

#pragma mark - Lifecycle
- (void)viewDidLoad {}
- (void)viewWillAppear:(BOOL)animated {}

#pragma mark - Custom Accessors
- (void)setCustomProperty:(id)value {}
- (id)customProperty {}

#pragma mark - Public
- (void)publicMethod {}

#pragma mark - Private
- (void)privateMethod {}

3. 空格與縮排

縮排使用 4 個空格,請在 Xcode 偏好設定中統一。大括號的擺放同一檔案內必須一致,可以同行開啟也可以換行開啟,但結尾一律換行。個人偏好是換行開啟、換行關閉:

if (user.isHappy) {
    // Do something
} else {
    // Do something else
}

4. 註解

註解很重要,但除了檔案開頭的版權宣告之外,更好的做法是讓代碼本身像文件一樣清楚——別怕名稱長,相信 Xcode 的自動補全。

實例變數應該在 .m 中宣告,或以 @property 形式在 .h 中宣告;若確實需要在 .h 中直接宣告,請加上 @private。使用 @private、@public 時前面要有一個縮排空格。

.h 文件力求精簡,能不公開的 API 就不要公開,寫進實作檔即可。屬性註解建議統一格式:

@property (nonatomic, assign) NSInteger xLineCount; /**< 格子橫線數量 */

這樣在設定屬性時,Xcode 的提示就會帶出對應說明。若不想每次手打,可以在 Xcode 中自訂 code snippet,把 /**< <#註釋描述#> */ 存成快捷片段。

方法註解建議採用:

/**
 * @brief 用一組數據初始化柱狀圖
 * @param frame 初始 frame
 * @param data  設定圖表百分比
 * @return 物件本身
 */
- (instancetype)initWithFrame:(CGRect)frame dictionary:(NSDictionary *)data;

小技巧:有不少插件能自動生成註釋骨架,推薦 VVDocumenter。

5. 命名

iOS 中宣告屬性、方法一律採用駝峰式命名:類名首字母大寫,方法與參數首字母小寫。方法命名要讓人讀起來像一句話,能傳達意圖;取值方法不要加 get 前綴(會與系統的 getter 慣例混淆)。變數以小寫字母開頭,常量以小寫 k 開頭、後續單詞首字母大寫。參數過多時可換行並用冒號對齊,保持視覺整齊。

6. 底線前綴

使用屬性時,一律透過 self. 存取與修改,讓屬性在視覺上與區域變數區分開來。唯一的例外是初始化方法:在 init 系列方法中直接使用實例變數(_variableName),以避開 getter/setter 可能的副作用。區域變數不應帶底線。

7. 方法簽名

方法型別(- 或 +)之後要有一個空格,各段之間也要有空格,參數前需搭配描述性的關鍵字。「and」這個字保留給真正有並列語意的方法,不要拿來串接多個參數:

- (void)setExampleText:(NSString *)text image:(UIImage *)image;
- (void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag;
- (id)viewWithTag:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width height:(CGFloat)height;

8. 變數

變數名稱盡量具描述性,避免使用單字符命名(for 迴圈的計數器除外)。星號屬於變數宣告的一部分,寫成 NSString *text,而不是 NSString* text 或 NSString * text。

9. 屬性特性

所有屬性特性都要明確寫出,方便新人閱讀。順序為 storage、atomicity,與 Interface Builder 自動產生的代碼一致:

@property (weak, nonatomic) IBOutlet UIView *containerView;
@property (strong, nonatomic) NSString *tutorialName;

10. 點語法

點語法是存取屬性的簡潔寫法,底層仍會呼叫 getter/setter。存取與修改屬性時一律使用點語法,[] 則保留給一般方法呼叫。

11. 字面值

建立不可變的 NSString、NSDictionary、NSArray、NSNumber 時,應使用字面值語法。特別注意:nil 不能放進 NSArray 與 NSDictionary 的字面值,否則會直接 crash。

應該:

NSArray *names = @[@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul"];
NSDictionary *productManagers = @{@"iPhone": @"Kate", @"iPad": @"Kamal", @"Mobile Web": @"Bill"};
NSNumber *shouldUseLiterals = @YES;
NSNumber *buildingStreetNumber = @10018;

不應該:

NSArray *names = [NSArray arrayWithObjects:@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul", nil];
NSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys:
                                 @"Kate", @"iPhone", @"Kamal", @"iPad", @"Bill", @"Mobile Web", nil];
NSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];
NSNumber *buildingStreetNumber = [NSNumber numberWithInteger:10018];

12. 常量

常量便於重複使用,也便於集中修改。應使用 static 宣告而非 #define,除非你確實需要宏的特性。

應該:

static NSString * const RWTAboutViewControllerCompanyName = @"RayWenderlich.com";
static CGFloat const RWTImageThumbnailHeight = 50.0;

不應該:

#define CompanyName @"RayWenderlich.com"
#define thumbnailHeight 2

13. 枚舉類型

定義 enum 時推薦使用固定底層型別,這能提供更强的型別檢查與自動補全。SDK 提供了 NS_ENUM() 宏來鼓勵這種寫法:

typedef NS_ENUM(NSInteger, RWTLeftMenuTopItemType) {
    RWTLeftMenuTopItemMain,
    RWTLeftMenuTopItemShows,
    RWTLeftMenuTopItemSchedule
};

// 需要顯式賦值時
typedef NS_ENUM(NSInteger, RWTGlobalConstants) {
    RWTPinSizeMin = 1,
    RWTPinSizeMax = 5,
    RWTPinCountMin = 100,
    RWTPinCountMax = 500
};

舊式的 k-style 常量定義應該避免,除非你在寫 Core Foundation 的 C 代碼:

// 不應該
enum GlobalConstants {
    kMaxPinSize = 5,
    kMaxPinCount = 500
};

14. Case 語句

case 內部只有在編譯器要求時才需要大括號;當某個 case 包含多行代碼時,請加上大括號。多個 case 共用同一段邏輯時,可以使用刻意穿透(fall-through),但務必加註解說明:

switch (condition) {
    case 1:
        // ...
        break;
    case 2: {
        // 多行範例,用大括號包起來
        break;
    }
    case 3:
        // ** fall-through! **
    case 4:
        // 1 與 2 都會執行到這裡
        break;
    default:
        break;
}

對枚舉做 switch 時,由於 case 已涵蓋所有可能值,default 並非必要。

15. 私有屬性

私有屬性應宣告在實作檔的類別擴充(匿名分類)中。命名分類(如 RWTPrivate 或 private)不該使用,除非你是在擴充其他類。匿名分類可透過 +Private.h 的命名約定開放給測試使用:

@interface RWTDetailViewController ()

@property (strong, nonatomic) GADBannerView *googleAdView;
@property (strong, nonatomic) ADBannerView *iAdView;
@property (strong, nonatomic) UIWebView *adXWebView;

@end

16. 布爾值

Objective-C 使用 YES 與 NO,true 與 false 只在 CoreFoundation、C 或 C++ 代碼中使用。由於 nil 會被解析為 NO,條件式中不必再與 nil 比較;也不要拿物件直接和 YES 比較,因為 YES 定義為 1,而 BOOL 實際上是 8 位元。

應該:

if (someObject) {}
if (![anotherObject boolValue]) {}

不應該:

if (someObject == nil) {}
if ([anotherObject boolValue] == NO) {}
if (isAwesome == YES) {}   // 永遠不要這樣寫
if (isAwesome == true) {}  // 永遠不要這樣寫

若 BOOL 屬性名稱是形容詞,可省略 is 前綴,但要用 getter 指定慣用名稱:

@property (assign, getter=isEditable) BOOL editable;

17. 條件語句

即使主體只有一行,也必須用大括號包起來。這些錯誤包括:日後補上第二行時以為它屬於 if;更危險的是某行代碼被註解掉後,下一行在不知不覺間變成 if 的一部分。加上大括號也讓整體風格保持一致:

應該:

if (!error) {
    return success;
}

不應該:

if (!error) return success;

18. 三元運算子

三元運算子 ?: 只在能提升清晰度與簡潔度時使用,最適合「依條件賦值」的單一條件場景。多條件判斷改用 if 或重構為實例變數會更易讀。非 boolean 值參與比較時加上括號可提升可讀性,boolean 本身則不需要。

應該:

NSInteger value = 5;
result = (value != 0) ? x : y;

BOOL isHorizontal = YES;
result = isHorizontal ? x : y;

不應該:

result = a > b ? x = c > d ? c : d : y;

19. Init 方法

init 方法應遵循 Apple 的命名慣例,回傳型別使用 instancetype 而非 id。

- (instancetype)init {
    self = [super init];
    if (self) {
        // ...
    }
    return self;
}

20. 類構造方法

類構造方法同樣應該回傳 instancetype,讓編譯器能正確推斷結果型別。

@interface Airplane

+ (instancetype)airplaneWithType:(RWTAirplaneType)type;

@end

21. CGRect 相關函數

取得 CGRect 的 x、y、width、height 時,應使用 CGGeometry 函數,而不是直接透過結構體存取。Apple 在 CGGeometry 文件中明確指出:這些函數在計算結果時會隱式標準化矩形,因此應避免直接讀寫 CGRect 中儲存的數據。

應該:

CGRect frame = self.view.frame;
CGFloat x      = CGRectGetMinX(frame);
CGFloat y      = CGRectGetMinY(frame);
CGFloat width  = CGRectGetWidth(frame);
CGFloat height = CGRectGetHeight(frame);
CGRect newFrame = CGRectMake(0.0, 0.0, width, height);

不應該:

CGRect frame = self.view.frame;
CGFloat x = frame.origin.x;
CGFloat y = frame.origin.y;
CGFloat width = frame.size.width;
CGFloat height = frame.size.height;

22. 黃金路徑

寫條件式時,左側(不縮排的那層)應該是「golden / happy path」。也就是盡量不要嵌套 if,多個 return 完全沒問題:

應該:

- (void)someMethod {
    if (![someOther boolValue]) {
        return;
    }
    // Do something important
}

不應該:

- (void)someMethod {
    if ([someOther boolValue]) {
        // Do something important
    }
}

23. 錯誤處理

當方法透過參數引用回傳 error 時,應該判斷回傳值,而不是判斷 error 變數。

應該:

NSError *error;
if (![self trySomethingWithError:&error]) {
    // Handle Error
}

不應該:

NSError *error;
[self trySomethingWithError:&error];
if (error) {
    // Handle Error
}

原因是部分 Apple API 在成功的情況下仍會往 error 參數寫入垃圾值,判斷 error 會導致誤判甚至 crash。

24. 單例模式

單例必須用執行緒安全的方式建立共享實例。

+ (instancetype)sharedInstance {
    static id sharedInstance = nil;
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        sharedInstance = [[self alloc] init];
    });
    return sharedInstance;
}

25. 換行

過長的方法呼叫應該拆成多行,下一行以兩個空格縮進對齊冒號,兼顧螢幕閱讀與列印可讀性。

self.productsRequest = [[SKProductsRequest alloc]
                        initWithProductIdentifiers:productIdentifiers];

26. Xcode 專案結構

實體檔案應該與 Xcode 專案中的群組保持同步,避免檔案不斷膨脹。新增 group 時也要在檔案系統中實際建立對應目錄。代碼除了依型別分組,更建議依功能分組,這樣結構會清楚得多。

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