這篇編碼風(fēng)格指南概括了 http://raywenderlich.com 的編碼規(guī)范，可能有些刪減或修改。

介紹

我們制定Objective-C編碼規(guī)范的原因是我們能夠在我們的書，教程和初學(xué)者工具包的代碼保持優(yōu)雅和一致。即使我們有很多不同的作者來完成不同的書籍。

這里編碼規(guī)范有可能與你看到的其他Objective-C編碼規(guī)范不同，因?yàn)樗饕菫榱舜蛴『蛍eb的易讀性。

關(guān)于作者

這編碼規(guī)范的創(chuàng)建是由很多來自raywenderlich.com團(tuán)隊(duì)成員在Nicholas Waynik的帶領(lǐng)下共同完成的。團(tuán)隊(duì)成員有：Soheil Moayedi Azarpour, Ricardo Rendon Cepeda, Tony Dahbura, Colin Eberhardt, Matt Galloway, Greg Heo, Matthijs Hollemans, Christopher LaPollo, Saul Mora, Andy Pereira, Mic Pringle, Pietro Rea, Cesare Rocchi, Marin Todorov, Nicholas Waynik和Ray Wenderlich

我們也非常感謝New York Times 和Robots & Pencils'Objective-C編碼規(guī)范的作者。這兩個(gè)編碼規(guī)范為本指南的創(chuàng)建提供很好的起點(diǎn)。

背景

這里有些關(guān)于編碼風(fēng)格Apple官方文檔，如果有些東西沒有提及，可以在以下文檔來查找更多細(xì)節(jié)：

• The Objective-C Programming Language
• Cocoa Fundamentals Guide
• Coding Guidelines for Cocoa
• iOS App Programming Guide

語言

應(yīng)該使用US英語.

應(yīng)該:

UIColor *myColor = [UIColor whiteColor];

不應(yīng)該:

UIColor *myColour = [UIColor whiteColor];

代碼組織

在函數(shù)分組和protocol/delegate實(shí)現(xiàn)中使用#pragma mark -來分類方法，要遵循以下一般結(jié)構(gòu)：

#pragma mark - Lifecycle
- (instancetype)init {}
- (void)dealloc {}
- (void)viewDidLoad {}
- (void)viewWillAppear:(BOOL)animated {}
- (void)didReceiveMemoryWarning {}

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

#pragma mark - IBActions/Event Response
- (IBAction)submitData:(id)sender {}
- (void)someButtonDidPressed:(UIButton*)button

#pragma mark - Protocol conformance
#pragma mark - UITextFieldDelegate
#pragma mark - UITableViewDataSource
#pragma mark - UITableViewDelegate

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

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

#pragma mark - NSCopying
- (id)copyWithZone:(NSZone *)zone {}

#pragma mark - NSObject
- (NSString *)description {}

空格

• 縮進(jìn)使用4個(gè)空格，確保在Xcode偏好設(shè)置來設(shè)置。(raywenderlich.com使用2個(gè)空格)
• 方法大括號(hào)和其他大括號(hào)(if/else/switch/while 等.)總是在同一行語句打開但在新行中關(guān)閉。

應(yīng)該:

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

不應(yīng)該:

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

• 在方法之間應(yīng)該有且只有一行，這樣有利于在視覺上更清晰和更易于組織。在方法內(nèi)的空白應(yīng)該分離功能，但通常都抽離出來成為一個(gè)新方法。
• 優(yōu)先使用auto-synthesis。但如果有必要，@synthesize 和 @dynamic應(yīng)該在實(shí)現(xiàn)中每個(gè)都聲明新的一行。
• 應(yīng)該避免以冒號(hào)對(duì)齊的方式來調(diào)用方法。因?yàn)橛袝r(shí)方法簽名可能有3個(gè)以上的冒號(hào)和冒號(hào)對(duì)齊會(huì)使代碼更加易讀。請(qǐng)不要這樣做，盡管冒號(hào)對(duì)齊的方法包含代碼塊，因?yàn)閄code的對(duì)齊方式令它難以辨認(rèn)。

應(yīng)該:

// blocks are easily readable
[UIView animateWithDuration:1.0 animations:^{
  // something
} completion:^(BOOL finished) {
  // something
}];

不應(yīng)該:

// colon-aligning makes the block indentation hard to read
[UIView animateWithDuration:1.0
                 animations:^{
                     // something
                 }
                 completion:^(BOOL finished) {
                     // something
                 }];

注釋

當(dāng)需要注釋時(shí)，注釋應(yīng)該用來解釋這段特殊代碼為什么要這樣做。任何被使用的注釋都必須保持最新或被刪除。

一般都避免使用塊注釋，因?yàn)榇a盡可能做到自解釋，只有當(dāng)斷斷續(xù)續(xù)或幾行代碼時(shí)才需要注釋。例外：這不應(yīng)用在生成文檔的注釋

命名

Apple命名規(guī)則盡可能堅(jiān)持，特別是與這些相關(guān)的memory management rules (NARC)。

長的，描述性的方法和變量命名是好的。

應(yīng)該:

UIButton *settingsButton;

不應(yīng)該:

UIButton *setBut;

三個(gè)字符前綴應(yīng)該經(jīng)常用在類和常量命名，但在Core Data的實(shí)體名中應(yīng)被忽略。對(duì)于官方的raywenderlich.com書、初學(xué)者工具包或教程，前綴'RWT'應(yīng)該被使用。

常量應(yīng)該使用駝峰式命名規(guī)則，所有的單詞首字母大寫和加上與類名有關(guān)的前綴。

應(yīng)該:

static NSTimeInterval const RWTTutorialViewControllerNavigationFadeAnimationDuration = 0.3;

不應(yīng)該:

static NSTimeInterval const fadetime = 1.7;

屬性也是使用駝峰式，但首單詞的首字母小寫。對(duì)屬性使用auto-synthesis，而不是手動(dòng)編寫@ synthesize語句，除非你有一個(gè)好的理由。

應(yīng)該:

@property (strong, nonatomic) NSString *descriptiveVariableName;

不應(yīng)該:

id varnm;

下劃線

當(dāng)使用屬性時(shí)，實(shí)例變量應(yīng)該使用self.來訪問和改變。這就意味著所有屬性將會(huì)視覺效果不同，因?yàn)樗鼈兦懊娑加?code>self.。

但有一個(gè)特例：在初始化方法里，實(shí)例變量(例如，_variableName)應(yīng)該直接被使用來避免getters/setters潛在的副作用。

局部變量不應(yīng)該包含下劃線。

方法

在方法簽名中，應(yīng)該在方法類型(-/+ 符號(hào))之后有一個(gè)空格。在方法各個(gè)段之間應(yīng)該也有一個(gè)空格(符合Apple的風(fēng)格)。在參數(shù)之前應(yīng)該包含一個(gè)具有描述性的關(guān)鍵字來描述參數(shù)。

"and"這個(gè)詞的用法應(yīng)該保留。它不應(yīng)該用于多個(gè)參數(shù)來說明，就像initWithWidth:height以下這個(gè)例子：

應(yīng)該:

- (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;

不應(yīng)該:

-(void)setT:(NSString *)text i:(UIImage *)image;
- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
- (id)taggedView:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width andHeight:(CGFloat)height;
- (instancetype)initWith:(int)width and:(int)height;  // Never do this.

變量

變量盡量以描述性的方式來命名。單個(gè)字符的變量命名應(yīng)該盡量避免，除了在for()循環(huán)。

星號(hào)表示變量是指針。例如， NSString *text 既不是 NSString* text 也不是 NSString * text，除了一些特殊情況下常量。

私有變量 應(yīng)該盡可能代替實(shí)例變量的使用。盡管使用實(shí)例變量是一種有效的方式，但更偏向于使用屬性來保持代碼一致性。

通過使用'back'屬性(_variable，變量名前面有下劃線)直接訪問實(shí)例變量應(yīng)該盡量避免，除了在初始化方法(init, initWithCoder:, 等…)，dealloc 方法和自定義的setters和getters。想了解關(guān)于如何在初始化方法和dealloc直接使用Accessor方法的更多信息，查看這里

應(yīng)該:

@interface RWTTutorial : NSObject

@property (strong, nonatomic) NSString *tutorialName;

@end

不應(yīng)該:

@interface RWTTutorial : NSObject {
  NSString *tutorialName;
}

屬性特性

所有屬性特性應(yīng)該顯式地列出來，有助于新手閱讀代碼。屬性特性的順序應(yīng)該是storage、atomicity，與在Interface Builder連接UI元素時(shí)自動(dòng)生成代碼一致。

應(yīng)該:

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

不應(yīng)該:

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

NSString應(yīng)該使用copy 而不是 strong的屬性特性。

為什么？即使你聲明一個(gè)NSString的屬性，有人可能傳入一個(gè)NSMutableString的實(shí)例，然后在你沒有注意的情況下修改它。

應(yīng)該:

@property (copy, nonatomic) NSString *tutorialName;

不應(yīng)該:

@property (strong, nonatomic) NSString *tutorialName;

點(diǎn)符號(hào)語法

點(diǎn)語法是一種很方便封裝訪問方法調(diào)用的方式。當(dāng)你使用點(diǎn)語法時(shí)，通過使用getter或setter方法，屬性仍然被訪問或修改。想了解更多，閱讀這里

點(diǎn)語法應(yīng)該總是被用來訪問和修改屬性，因?yàn)樗勾a更加簡潔。[]符號(hào)更偏向于用在其他例子。

應(yīng)該:

NSInteger arrayCount = [self.array count];
view.backgroundColor = [UIColor orangeColor];
[UIApplication sharedApplication].delegate;

不應(yīng)該:

NSInteger arrayCount = self.array.count;
[view setBackgroundColor:[UIColor orangeColor]];
UIApplication.sharedApplication.delegate;

字面值

NSString, NSDictionary, NSArray, 和 NSNumber的字面值應(yīng)該在創(chuàng)建這些類的不可變實(shí)例時(shí)被使用。請(qǐng)?zhí)貏e注意nil值不能傳入NSArray和NSDictionary字面值，因?yàn)檫@樣會(huì)導(dǎo)致crash。

應(yīng)該:

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

不應(yīng)該:

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];

常量

常量是容易重復(fù)被使用和無需通過查找和代替就能快速修改值。常量應(yīng)該使用static來聲明而不是使用#define，除非顯式地使用宏。

應(yīng)該:

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

static CGFloat const RWTImageThumbnailHeight = 50.0;

不應(yīng)該:

#define CompanyName @"RayWenderlich.com"

#define thumbnailHeight 2

枚舉類型

當(dāng)使用enum時(shí)，推薦使用新的固定基本類型規(guī)格，因?yàn)樗懈鼜?qiáng)的類型檢查和代碼補(bǔ)全。現(xiàn)在SDK有一個(gè)宏NS_ENUM()來幫助和鼓勵(lì)你使用固定的基本類型。

例如:

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

你也可以顯式地賦值(展示舊的k-style常量定義)：

typedef NS_ENUM(NSInteger, RWTGlobalConstants) {
  RWTPinSizeMin = 1,
  RWTPinSizeMax = 5,
  RWTPinCountMin = 100,
  RWTPinCountMax = 500,
};

舊的k-style常量定義應(yīng)該避免除非編寫Core Foundation C的代碼。

不應(yīng)該:

enum GlobalConstants {
  kMaxPinSize = 5,
  kMaxPinCount = 500,
};

Case語句

大括號(hào)在case語句中并不是必須的，除非編譯器強(qiáng)制要求。當(dāng)一個(gè)case語句包含多行代碼時(shí)，大括號(hào)應(yīng)該加上。

switch (condition) {
  case 1:
    // ...
    break;
  case 2: {
    // ...
    // Multi-line example using braces
    break;
  }
  case 3:
    // ...
    break;
  default: 
    // ...
    break;
}

有很多次，當(dāng)相同代碼被多個(gè)cases使用時(shí)，一個(gè)fall-through應(yīng)該被使用。一個(gè)fall-through就是在case最后移除'break'語句，這樣就能夠允許執(zhí)行流程跳轉(zhuǎn)到下一個(gè)case值。為了代碼更加清晰，一個(gè)fall-through需要注釋一下。

switch (condition) {
  case 1:
    // ** fall-through! **
  case 2:
    // code executed for values 1 and 2
    break;
  default: 
    // ...
    break;
}

當(dāng)在switch使用枚舉類型時(shí)，'default'是不需要的。例如：

RWTLeftMenuTopItemType menuType = RWTLeftMenuTopItemMain;

switch (menuType) {
  case RWTLeftMenuTopItemMain:
    // ...
    break;
  case RWTLeftMenuTopItemShows:
    // ...
    break;
  case RWTLeftMenuTopItemSchedule:
    // ...
    break;
}

私有屬性

私有屬性應(yīng)該在類的實(shí)現(xiàn)文件中的類擴(kuò)展(匿名分類)中聲明，命名分類(比如RWTPrivate或private)應(yīng)該從不使用除非是擴(kuò)展其他類。匿名分類應(yīng)該通過使用<headerfile>+Private.h文件的命名規(guī)則暴露給測試。

例如:

@interface RWTDetailViewController ()

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

@end

布爾值

Objective-C使用YES和NO。因?yàn)?code>true和false應(yīng)該只在CoreFoundation，C或C++代碼使用。既然nil解析成NO，所以沒有必要在條件語句比較。不要拿某樣?xùn)|西直接與YES比較，因?yàn)?code>YES被定義為1和一個(gè)BOOL能被設(shè)置為8位。

這是為了在不同文件保持一致性和在視覺上更加簡潔而考慮。

應(yīng)該:

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

不應(yīng)該:

if (someObject == nil) {}
if ([anotherObject boolValue] == NO) {}
if (isAwesome == YES) {} // Never do this.
if (isAwesome == true) {} // Never do this.

如果BOOL屬性的名字是一個(gè)形容詞，屬性就能忽略"is"前綴，但要指定get訪問器的慣用名稱。例如：

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

文字和例子從這里引用Cocoa Naming Guidelines

條件語句

條件語句主體為了防止出錯(cuò)應(yīng)該使用大括號(hào)包圍，即使條件語句主體能夠不用大括號(hào)編寫(如，只用一行代碼)。這些錯(cuò)誤包括添加第二行代碼和期望它成為if語句；還有，even more dangerous defect可能發(fā)生在if語句里面一行代碼被注釋了，然后下一行代碼不知不覺地成為if語句的一部分。除此之外，這種風(fēng)格與其他條件語句的風(fēng)格保持一致，所以更加容易閱讀。

應(yīng)該:

if (!error) {
  return success;
}

不應(yīng)該:

if (!error)
  return success;

或

if (!error) return success;

三元操作符

當(dāng)需要提高代碼的清晰性和簡潔性時(shí)，三元操作符?:才會(huì)使用。單個(gè)條件求值常常需要它。多個(gè)條件求值時(shí)，如果使用if語句或重構(gòu)成實(shí)例變量時(shí)，代碼會(huì)更加易讀。一般來說，最好使用三元操作符是在根據(jù)條件來賦值的情況下。

Non-boolean的變量與某東西比較，加上括號(hào)()會(huì)提高可讀性。如果被比較的變量是boolean類型，那么就不需要括號(hào)。

應(yīng)該:

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

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

不應(yīng)該:

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

Init方法

Init方法應(yīng)該遵循Apple生成代碼模板的命名規(guī)則。返回類型應(yīng)該使用instancetype而不是id

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

查看關(guān)于instancetype的文章Class Constructor Methods

類構(gòu)造方法

當(dāng)類構(gòu)造方法被使用時(shí)，它應(yīng)該返回類型是instancetype而不是id。這樣確保編譯器正確地推斷結(jié)果類型。

@interface Airplane
+ (instancetype)airplaneWithType:(RWTAirplaneType)type;
@end

關(guān)于更多instancetype信息，請(qǐng)查看NSHipster.com

CGRect函數(shù)

當(dāng)訪問CGRect里的x, y, width, 或 height時(shí)，應(yīng)該使用CGGeometry函數(shù)而不是直接通過結(jié)構(gòu)體來訪問。引用Apple的CGGeometry:

在這個(gè)參考文檔中所有的函數(shù)，接受CGRect結(jié)構(gòu)體作為輸入，在計(jì)算它們結(jié)果時(shí)隱式地標(biāo)準(zhǔn)化這些rectangles。因此，你的應(yīng)用程序應(yīng)該避免直接訪問和修改保存在CGRect數(shù)據(jù)結(jié)構(gòu)中的數(shù)據(jù)。相反，使用這些函數(shù)來操縱rectangles和獲取它們的特性。

應(yīng)該:

CGRect frame = self.view.frame;

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

不應(yīng)該:

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;
CGRect frame = (CGRect){ .origin = CGPointZero, .size = frame.size };

黃金路徑

當(dāng)使用條件語句編碼時(shí)，左手邊的代碼應(yīng)該是"golden" 或 "happy"路徑。也就是不要嵌套if語句，多個(gè)返回語句也是OK。

應(yīng)該:

- (void)someMethod {
  if (![someOther boolValue]) {
 return;
  }

  //Do something important
}

不應(yīng)該:

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

錯(cuò)誤處理

當(dāng)方法通過引用來返回一個(gè)錯(cuò)誤參數(shù)，判斷返回值而不是錯(cuò)誤變量。

應(yīng)該:

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

不應(yīng)該:

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

在成功的情況下，有些Apple的APIs記錄垃圾值(garbage values)到錯(cuò)誤參數(shù)(如果non-NULL)，那么判斷錯(cuò)誤值會(huì)導(dǎo)致false負(fù)值和crash。

單例模式

單例對(duì)象應(yīng)該使用線程安全模式來創(chuàng)建共享實(shí)例。

+ (instancetype)sharedInstance {
  static id sharedInstance = nil;

  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    sharedInstance = [[self alloc] init];
  });

  return sharedInstance;
}

這會(huì)防止possible and sometimes prolific crashes.

換行符

換行符是一個(gè)很重要的主題，因?yàn)樗娘L(fēng)格指南主要為了打印和網(wǎng)上的可讀性。

例如:

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

一行很長的代碼應(yīng)該分成兩行代碼，下一行用兩個(gè)空格隔開。

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

Xcode工程

物理文件應(yīng)該與Xcode工程文件保持同步來避免文件擴(kuò)張。任何Xcode分組的創(chuàng)建應(yīng)該在文件系統(tǒng)的文件體現(xiàn)。代碼不僅是根據(jù)類型來分組，而且還可以根據(jù)功能來分組，這樣代碼更加清晰。

盡可能在target的Build Settings打開"Treat Warnings as Errors，和啟用以下additional warnings。如果你需要忽略特殊的警告，使用 Clang's pragma feature。

其他Objective-C編碼規(guī)范

如果我們的編碼規(guī)范不符合你的口味，可以查看其他的編碼規(guī)范：

• Robots & Pencils
• New York Times
• Google
• GitHub
• Adium
• Sam Soffes
• CocoaDevCentral
• Luke Redpath
• Marcus Zarra