Object-C 開(kāi)發(fā)代碼規(guī)范
概要
Object-C是一門(mén)面向?qū)ο蟮膭?dòng)態(tài)編程語(yǔ)言,主要用于編寫(xiě)IOS和MAC應(yīng)用程序。關(guān)于Object-C蘋(píng)果已經(jīng)有很好的總結(jié):
https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html
本文主要是整合了上述文檔的翻譯、自己的編程經(jīng)驗(yàn)和其它相關(guān)資料,為公司總結(jié)出一份通用的編碼規(guī)范。
代碼格式
每一行的最大長(zhǎng)度
同樣的,在Xcode > Preferences > Text Editing > Page guide at column中將最大行長(zhǎng)設(shè)置為80,過(guò)長(zhǎng)的一行代碼將會(huì)導(dǎo)致可讀性問(wèn)題。
函數(shù)的書(shū)寫(xiě)
一個(gè)典型的Object-C函數(shù)應(yīng)該是這樣的:
- (void)createMethodParam:(NSString*)str type:(NSInteger)type{
……
}
在-和(void)之間應(yīng)該有一個(gè)空格,第一個(gè)大括號(hào){的位置在函數(shù)所在行的末尾,同樣應(yīng)該有一個(gè)空格。
如果一個(gè)函數(shù)有特別多的參數(shù)或者名稱很長(zhǎng),應(yīng)該將其按照:來(lái)對(duì)齊分行顯示:
- (void)initWithModel:(Model *)model
param1:(NSString *) param1
param2:(NSString *) param2
param3:(NSString *) param3
param4:(NSString *) param4;
在分行時(shí),如果第一段名稱過(guò)短,后續(xù)名稱可以以Tab的長(zhǎng)度為單位進(jìn)行縮進(jìn): - (void)initWithModel:(Model *)model
param1:(NSString *) param1
paramString2:(NSString *) param2
param4:(NSString *) param4;
函數(shù)發(fā)送
函數(shù)發(fā)送的格式和書(shū)寫(xiě)格式差不多,可以按照函數(shù)的長(zhǎng)短來(lái)選擇寫(xiě)在一行或者是分成多行:
//寫(xiě)在一行
[myObject doFooWith:arg1 name:arg2 error:arg3];
//分行寫(xiě),按照:對(duì)齊
[myObject doFooWith:arg1
name:arg2
error:arg3];
//第一段名稱過(guò)短的話后續(xù)可以進(jìn)行縮進(jìn)
[myObj short:arg1
longKeyword:arg2
evenLongerKeyword:arg3
error:arg4];
@public和@private標(biāo)記符
@public和@private標(biāo)記符應(yīng)該以一個(gè)空格來(lái)進(jìn)行縮進(jìn):
@interface MyClass : NSObject {
@public
...
@private
...
}
@end
協(xié)議(Protocols)
在書(shū)寫(xiě)協(xié)議的時(shí)候注意用<>括起來(lái)的協(xié)議和類型名之間是沒(méi)有空格的,比如DemoClass()<DemoClassDelegate>,這個(gè)規(guī)則適用所有書(shū)寫(xiě)協(xié)議的地方,包括函數(shù)聲明、類生命、實(shí)例變量等等:
@interface MyProtocoledClass : NSObject<NSWindowDelegate>{
@private
id<MyFancyDelegate> _delegate;
}
- (void)setDelegate:(id<MyFancyDelegate>)aDelegate;
@end
閉包(Blocks)
根據(jù)block的長(zhǎng)度,有不同的書(shū)寫(xiě)規(guī)則:
- 較短的block可以寫(xiě)在一行內(nèi)。
- 如果分行顯示的話,block的右括號(hào)}應(yīng)該和調(diào)用block那行代碼的第一個(gè)非空字符對(duì)齊。
- block內(nèi)的代碼采用4個(gè)空格縮進(jìn)。
- 如果block過(guò)于龐大,應(yīng)該單獨(dú)聲明一個(gè)變量來(lái)使用。
-
和(之間,和{之間都沒(méi)有空格,參數(shù)列表的右括號(hào)}和{之間又一個(gè)空格。
//較短的block寫(xiě)在一行內(nèi)
[operation setCompletionBlock:^{ [self onOperationDone]; }];
//分行書(shū)寫(xiě)的block,內(nèi)部使用4空格縮進(jìn)
[operation setCompletionBlock:^{
[self.delegate newDataAvailable];
}];
//使用C語(yǔ)言API調(diào)用的block遵循同樣的書(shū)寫(xiě)規(guī)則
dispatch_async(_fileIOQueue, ^{
NSString* path = [self sessionFilePath];
if (path) {
// ...
}
});
//較長(zhǎng)的block關(guān)鍵字可以縮進(jìn)后在新行書(shū)寫(xiě),注意block的右括號(hào)}和調(diào)用block那行代碼的第一個(gè)非空字符對(duì)齊
[[SessionService sharedService]
loadWindowWithCompletionBlock:^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}
}];
//較長(zhǎng)的block參數(shù)列表同樣可以縮進(jìn)后在新行書(shū)寫(xiě)
[[SessionService sharedService]
loadWindowWithCompletionBlock:
^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}
}];
//龐大的block應(yīng)該單獨(dú)定義成變量使用
void (^largeBlock)(void) = ^{
// ...
};
[_operationQueue addOperationWithBlock:largeBlock];
//在一個(gè)調(diào)用中使用多個(gè)block,注意到他們不是像函數(shù)那樣通過(guò):對(duì)齊的,而是同時(shí)進(jìn)行了4個(gè)空格的縮進(jìn)
[myObject doSomethingWith:arg1
firstBlock:^(Foo *a) {
// ...
}
secondBlock:^(Bar *b) {
// ...
}];
數(shù)據(jù)結(jié)構(gòu)的語(yǔ)法規(guī)范
應(yīng)該使用可讀性更好的語(yǔ)法來(lái)構(gòu)造NSArray、NSDictionary等數(shù)據(jù)結(jié)構(gòu),避免冗長(zhǎng)的alloc、init方法。
如果構(gòu)造代碼寫(xiě)在一行,需要在括號(hào)兩端留一個(gè)空格,使得被構(gòu)造的元素與構(gòu)造語(yǔ)法區(qū)分開(kāi)來(lái):
NSArray *array = @[ [foo description], [bar description] ];
NSDictionary *dict = @{ NSForegroundColorAttributeName:[NSColor redColor] };
如果構(gòu)造代碼不寫(xiě)在一行內(nèi),構(gòu)造元素需要使用兩個(gè)空格來(lái)進(jìn)行縮進(jìn),右括號(hào)]或者}寫(xiě)在新的一行,并且與調(diào)用語(yǔ)法那行代碼的第一個(gè)非空字符對(duì)齊:
NSArray *array = @[
@”This ”,
@”is ”,
@”an ”,
@”array ”
];
NSDictionary *dictionary = @{
NSFontAttributeName : [NSFont fontWithName: Helvetica-Bold size:12],
NSForegroundColorAttributeName : fontColor
};
構(gòu)造字典時(shí),字典的Key和Value與中間的冒號(hào):都要留有一個(gè)空格,多行書(shū)寫(xiě)時(shí),也可以將Value對(duì)齊:
//正確,冒號(hào):;前后留有一個(gè)空格
NSDictionary *option1 = @{
NSFontAttributeName : [NSFont fontWithName: Helvetica-Bold size:12],
NSForegroundColorAttributeName : fontColor
};
//正確,按照Value來(lái)對(duì)齊
NSDictionary *option2 = @{
NSFontAttributeName : [NSFont fontWithName:@Arial size:12],
NSForegroundColorAttributeName : fontColor
};
命名規(guī)范
基本原則
清晰
命名應(yīng)該盡可能的清晰和簡(jiǎn)潔,但在Object-C中,清晰比簡(jiǎn)潔更重要。由于Xcode強(qiáng)大的自動(dòng)補(bǔ)全功能,我們不必?fù)?dān)心名稱過(guò)長(zhǎng)的問(wèn)題。
//清晰
insertObject:atIndex:
//不清晰,insert的對(duì)象類型和at的位置屬性沒(méi)有說(shuō)明
insert:at:
//清晰
removeObjectAtIndex:
//不清晰,remove的對(duì)象類型沒(méi)有說(shuō)明,參數(shù)的作用沒(méi)有說(shuō)明
remove:
不要使用單詞的簡(jiǎn)寫(xiě),拼寫(xiě)出完整的單詞:
//清晰
destinationSelection
setBackgroundColor:
//不清晰,不要使用簡(jiǎn)寫(xiě)
destSel
setBkgdColor:
然而,有部分單詞簡(jiǎn)寫(xiě)在Object-C編碼過(guò)程中是非常常用的,以至于成為了一種規(guī)范,這些簡(jiǎn)寫(xiě)可以在代碼中直接使用,下面列舉了部分:
alloc == Allocate max == Maximum
alt == Alternate min == Minimum
app == Application msg == Message
calc == Calculate nib == Interface Builder archive
dealloc == Deallocate pboard == Pasteboard
func == Function rect == Rectangle
horiz == Horizontal Rep == Representation (used in class name such as NSBitmapImageRep).
info == Information temp == Temporary
init == Initialize vert == Vertical
int == Integer
命名方法或者函數(shù)時(shí)要避免歧義
//有歧義,是返回sendPort還是send一個(gè)Port?
sendPort
//有歧義,是返回一個(gè)名字屬性的值還是display一個(gè)name的動(dòng)作?
displayName
一致性
整個(gè)工程的命名風(fēng)格要保持一致性,最好和蘋(píng)果SDK的代碼保持統(tǒng)一。不同類中完成相似功能的方法應(yīng)該叫一樣的名字,比如我們總是用count來(lái)返回集合的個(gè)數(shù),不能在A類中使用count而在B類中使用getNumber
使用前綴
如果代碼需要打包成Framework給別的工程使用,或者工程項(xiàng)目非常龐大,需要拆分成不同的模塊,使用命名前綴是非常有用的。
前綴由大寫(xiě)的字母縮寫(xiě)組成,比如Cocoa中NS前綴代表Founation框架中的類,IB則代表Interface Builder框架。
可以在為類、協(xié)議、函數(shù)、常量以及typedef宏命名的時(shí)候使用前綴,但注意不要為成員變量或者方法使用前綴,因?yàn)樗麄儽旧砭桶陬惖拿臻g內(nèi)。
命名前綴的時(shí)候不要和蘋(píng)果SDK框架沖突。
命名類和協(xié)議(Class&Protocol)
類名以大寫(xiě)字母開(kāi)頭,應(yīng)該包含一個(gè)名詞來(lái)表示它代表的對(duì)象類型,同時(shí)可以加上必要的前綴,比如NSString, NSDate, NSScanner, NSApplication等等。
而協(xié)議名稱應(yīng)該清晰地表示它所執(zhí)行的行為,而且要和類名區(qū)別開(kāi)來(lái),所以通常使用ing詞尾來(lái)命名一個(gè)協(xié)議,比如NSCopying,NSLocking。
有些協(xié)議本身包含了很多不相關(guān)的功能,主要用來(lái)為某一特定類服務(wù),這時(shí)候可以直接用類名來(lái)命名這個(gè)協(xié)議,比如NSObject協(xié)議,它包含了id對(duì)象在生存周期內(nèi)的一系列方法。
命名頭文件(Headers)
源碼的頭文件名應(yīng)該清晰地暗示它的功能和包含的內(nèi)容:
如果頭文件內(nèi)只定義了單個(gè)類或者協(xié)議,直接用類名或者協(xié)議名來(lái)命名頭文件,比如NSLocale.h定義了NSLocale類。
如果頭文件內(nèi)定義了一系列的類、協(xié)議、類別,使用其中最主要的類名來(lái)命名頭文件,比如NSString.h定義了NSString和NSMutableString。
每一個(gè)Framework都應(yīng)該有一個(gè)和框架同名的頭文件,包含了框架中所有公共類頭文件的引用,比如Foundation.h
Framework中有時(shí)候會(huì)實(shí)現(xiàn)在別的框架中類的類別擴(kuò)展,這樣的文件通常使用被擴(kuò)展的框架名+Additions的方式來(lái)命名,比如NSBundleAdditions.h。
命名方法(Methods)
Objective-C的方法名通常都比較長(zhǎng),這是為了讓程序有更好地可讀性,按蘋(píng)果的說(shuō)法“好的方法名應(yīng)當(dāng)可以以一個(gè)句子的形式朗讀出來(lái)”。
方法一般以小寫(xiě)字母打頭,每一個(gè)后續(xù)的單詞首字母大寫(xiě),方法名中不應(yīng)該有標(biāo)點(diǎn)符號(hào)(包括下劃線),有兩個(gè)例外:
可以用一些通用的大寫(xiě)字母縮寫(xiě)打頭方法,比如PDF,TIFF等。
可以用帶下劃線的前綴來(lái)命名私有方法或者類別中的方法。
如果方法表示讓對(duì)象執(zhí)行一個(gè)動(dòng)作,使用動(dòng)詞打頭來(lái)命名,注意不要使用do,does這種多余的關(guān)鍵字,動(dòng)詞本身的暗示就足夠了:
//動(dòng)詞打頭的方法表示讓對(duì)象執(zhí)行一個(gè)動(dòng)作
- (void)invokeWithTarget:(id)target;
- (void)selectTabViewItem:(NSTabViewItem *)tabViewItem;
如果方法是為了獲取對(duì)象的一個(gè)屬性值,直接用屬性名稱來(lái)命名這個(gè)方法,注意不要添加get或者其他的動(dòng)詞前綴:
//合適,使用屬性名來(lái)命名方法
- (NSSize)cellSize;
//不合適,添加了多余的動(dòng)詞前綴
- (NSSize)calcCellSize;
- (NSSize)getCellSize;
對(duì)于有多個(gè)參數(shù)的方法,務(wù)必在每一個(gè)參數(shù)前都添加關(guān)鍵詞,關(guān)鍵詞應(yīng)當(dāng)清晰說(shuō)明參數(shù)的作用:
//正確,保證每個(gè)參數(shù)都有關(guān)鍵詞修飾
- (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag;
//錯(cuò)誤,遺漏關(guān)鍵詞
- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
//正確
- (id)viewWithTag:(NSInteger)aTag;
//錯(cuò)誤,關(guān)鍵詞的作用不清晰
- (id)taggedView:(int)aTag;
命名委托(Delegate)
當(dāng)特定的事件發(fā)生時(shí),對(duì)象會(huì)觸發(fā)它注冊(cè)的委托方法。委托是Objective-C中常用的傳遞消息的方式。委托有它固定的命名范式。
一個(gè)委托方法的第一個(gè)參數(shù)是觸發(fā)它的對(duì)象,第一個(gè)關(guān)鍵詞是觸發(fā)對(duì)象的類名,除非委托方法只有一個(gè)名為sender的參數(shù):
//第一個(gè)關(guān)鍵詞為觸發(fā)委托的類名
- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
//當(dāng)只有一個(gè)參數(shù)時(shí)可以省略類名
- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;
根據(jù)委托方法觸發(fā)的時(shí)機(jī)和目的,使用should,will,did等關(guān)鍵詞
(void)browserDidScroll:(NSBrowser *)sender;
(NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;、
(BOOL)windowShouldClose:(id)sender;
集合操作類方法(Collection Methods)
有些對(duì)象管理著一系列其它對(duì)象或者元素的集合,需要使用類似“增刪查改”的方法來(lái)對(duì)集合進(jìn)行操作,這些方法的命名范式一般為:
//集合操作范式
- (void)addElement:(elementType)anObj;
- (void)removeElement:(elementType)anObj;
- (NSArray *)elements;
//例子
- (void)addLayoutManager:(NSLayoutManager *)obj;
- (void)removeLayoutManager:(NSLayoutManager *)obj;
- (NSArray *)layoutManagers;
命名屬性和實(shí)例變量(Properties&Instance Variables)
屬性和對(duì)象的存取方法相關(guān)聯(lián),屬性的第一個(gè)字母小寫(xiě),后續(xù)單詞首字母大寫(xiě),不必添加前綴。屬性按功能命名成名詞或者動(dòng)詞:
//名詞屬性
@property (strong) NSString *title;
//動(dòng)詞屬性
@property (assign) BOOL showsAlpha;
屬性也可以命名成形容詞,這時(shí)候通常會(huì)指定一個(gè)帶有is前綴的get方法來(lái)提高可讀性:
@property (assign, getter=isEditable) BOOL editable;
命名常量(Constants)
如果要定義一組相關(guān)的常量,盡量使用枚舉類型(enumerations),枚舉類型的命名規(guī)則和函數(shù)的命名規(guī)則相同。 建議使用 NS_ENUM 和 NS_OPTIONS 宏來(lái)定義枚舉類型,參見(jiàn)官方的 https://developer.apple.com/library/content/releasenotes/ObjectiveC/ModernizationObjC/AdoptingModernObjective-C/AdoptingModernObjective-C.html 一文:
//定義一個(gè)枚舉
typedef NS_ENUM(NSInteger, NSMatrixMode) {
NSRadioModeMatrix,
NSHighlightModeMatrix,
NSListModeMatrix,
NSTrackModeMatrix
};
使用const定義浮點(diǎn)型或者單個(gè)的整數(shù)型常量,如果要定義一組相關(guān)的整數(shù)常量,應(yīng)該優(yōu)先使用枚舉。常量的命名規(guī)范和函數(shù)相同:
const float NSLightGray;
不要使用#define宏來(lái)定義常量,如果是整型常量,盡量使用枚舉,浮點(diǎn)型常量,使用const定義。#define通常用來(lái)給編譯器決定是否編譯某塊代碼,比如常用的: #ifdef DEBUG
注意到一般由編譯器定義的宏會(huì)在前后都有一個(gè)__,比如MACH。
注釋
讀沒(méi)有注釋代碼的痛苦你我都體會(huì)過(guò),好的注釋不僅能讓人輕松讀懂你的程序,還能提升代碼的逼格。注意注釋是為了讓別人看懂,而不是僅僅你自己。
文件注釋
每一個(gè)文件都必須寫(xiě)文件注釋,文件注釋通常包含
文件所在模塊
作者信息
歷史版本信息
版權(quán)信息
文件包含的內(nèi)容,作用
一段良好文件注釋的例子:
文件注釋的格式通常不作要求,能清晰易讀就可以了,但在整個(gè)工程中風(fēng)格要統(tǒng)一。
代碼注釋
好的代碼應(yīng)該是“自解釋”(self-documenting)的,但仍然需要詳細(xì)的注釋來(lái)說(shuō)明參數(shù)的意義、返回值、功能以及可能的副作用。
方法、函數(shù)、類、協(xié)議、類別的定義都需要注釋,推薦采用Apple的標(biāo)準(zhǔn)注釋風(fēng)格,好處是可以在引用的地方alt+點(diǎn)擊自動(dòng)彈出注釋,非常方便。