
簡介:
本文整理自 Apple 文件《Coding Guidelines for Cocoa》。這份文件原意是為 Cocoa 框架、外掛及公共 API 開發者提供編碼指導,實質上相當於 Apple 內部的編碼規範。在多人協作時,一份統一的代碼規範能大幅降低開發者之間的溝通成本,特此大力推薦。
目錄:
一、代碼命名基礎;二、方法;三、函數;四、Property 及其他;五、縮寫。
1.1 清晰
命名要盡量清晰又簡潔,無法兩全時,清晰永遠優先。

通常不應縮寫名稱,即使方法名很長也應完整拼寫。
你可能認為某個縮寫眾所周知,但其實未必,尤其是當團隊成員語言文化背景各異時。
少數歷史悠久的縮寫仍可沿用,詳見第五章。

API 命名要避免歧義,例如一個方法名有多種理解方式。

1.2 一致
盡力保持 Cocoa 編程接口命名一致。
若有疑惑,請瀏覽當前頭文件或參考文件。
當某個類別的方法使用多態時,一致性尤其重要。
不同類別裡,功能相同的方法命名也應相同。

1.3 避免自引用(self Reference)
命名不應自引用,這裡的自引用指的是在詞尾引用自身。

Mask 與 Notification 可忽略此規則。

前綴是編程接口命名的重要部分,它們區分了軟體的不同功能區域:
前綴可防止第三方開發者與 Apple 的命名衝突,也能避免 Apple 內部的命名衝突。
前綴有指定格式:由二到三個大寫字母組成,不使用下劃線與子前綴。
命名類別、協議、函數、常量和 typedef 結構體時使用前綴;方法名不使用前綴(因為它存在於特定類別的命名空間中),結構體欄位也不使用前綴。

命名 API 元素時,使用駝峰命名法(如 runTheWordsTogether),並注意以下約定:
方法名
小寫第一個字母,大寫之後所有單詞的首字母,不加前綴。
若方法名以眾所周知的大寫縮略詞開頭(如 TIFFRepresentation),此規則不適用。
fileExistsAtPath:isDirectory:
函數及常量名
使用與其關聯類別相同的前綴,並大寫首字母。
NSRunAlertPanel NSCellDisabled
標點符號
由多個單詞組成的名稱,別把標點符號作為名稱的一部分,分隔符(下劃線、破折號等)也不能使用。
避免使用下劃線作為私有方法的前綴,Apple 保留這一用法;強行使用可能導致命名衝突,覆蓋 Apple 既有方法,後果不堪設想。實例變量使用下劃線前綴則是允許的。
class
class 的名稱應包含一個名詞,用以表明這個類別是什麼(或做了什麼),並擁有合適的前綴,如 NSString、NSDate、NSScanner、UIApplication、UIButton。
不關聯 class 的 protocol
大多數 protocol 聚集了一堆相關方法,並不關聯 class;這類 protocol 使用 ing 形式以與 class 區分開來。

關聯 class 的 protocol
一些 protocol 聚集了一堆無關方法,並試圖與某個 class 關聯,由這個 class 主導;這種 protocol 與 class 同名,如 NSObject protocol。
頭文件的命名極其重要,因為它能指出頭文件包含的內容:
聲明一個孤立的 class 或 protocol 時,將聲明放入單獨的文件,並使頭文件名與該 class/protocol 相同。

聲明關聯的 class 或 protocol 時,將關聯的聲明(class/category/protocol)放入同一個頭文件,頭文件名與主要的 class/category/protocol 相同。

Framework 頭文件:每個 framework 都應有一個同名頭文件,並 Include 了框架內其他所有頭文件。

若要在一個 framework 中為另一個 framework 的 class category 添加方法,加上單詞「Additions」,如 Application Kit 的 NSBundleAdditions.h。
若你有一組關聯的函數、常量、結構體或其他數據類型,將它們放進一個名字合適的頭文件中,如 Application Kit 的 NSGraphics.h。
以小寫字母開始,之後單詞首字母大寫;以眾所周知的縮寫開始時可大寫,如 TIFF、PDF;私有方法可加前綴。
若方法代表對象接收的動作,以動詞開始,不要使用 do 或 does(助動詞在此少有實際意義),也不要在動詞前使用副詞和形容詞。
- (void)invokeWithTarget:(id)target; - (void)selectTabViewItem:(NSTabViewItem *)tabViewItem
若方法返回接收者的屬性,以「接收者 + 屬性」命名;除非間接返回多個值,否則不要使用 get(以與 accessor methods 區分)。

在所有參數之前使用關鍵字。

確保參數前的關鍵字充分描述了參數。

創建自訂 init 方法時,記得指明關聯的元素。

不要用 and 來連接作為接收者屬性的關鍵字——參數一多就容易出問題;除非方法描述的是兩個獨立的操作,才用 and 連接它們。


若 property 表示名詞,格式如下:
- (type)noun;
- (void)setNoun:(type)aNoun;
- (BOOL)isAdjective;
- (NSString *)title; - (void)setTitle:(NSString *)aTitle;
若 property 表示形容詞,格式如下:
- (BOOL)isAdjective;
- (void)setAdjective:(BOOL)flag;
- (BOOL)isEditable; - (void)setEditable:(BOOL)flag;
若 property 表示動詞,格式如下(動詞用一般現在時):
- (BOOL)verbObject;
- (void)setVerbObject:(BOOL)flag;
- (BOOL)showsAlpha; - (void)setShowsAlpha:(BOOL)flag;
不要把動詞的過去分詞當作形容詞使用。你可以用情態動詞(can、should、will 等)來增加可讀性,但不要用 do 或 does。只有在方法需要間接返回多個值時才使用 get,而這類接收多個參數的方法應該能傳入 nil,因為調用者未必對每個參數都感興趣。



以發送消息的對象開始(省略前綴的類名並小寫首字母):
- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row; - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
此規則不適用兩種情況:只有一個 sender 參數的方法,以及響應 notification 的方法(唯一參數就是 notification):
- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender; - (void)windowDidChangeScreen:(NSNotification *)notification;
使用 did 和 will 來通知 delegate:did 表示某些事已發生,will 表示某些事將要發生。
- (void)browserDidScroll:(NSBrowser *)sender; - (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;
詢問 delegate 是否可以執行某個行為時,did 或 will 皆可,但 should 更貼切。
- (BOOL)windowShouldClose:(id)sender;
為了管理集合中的元素,集合應有這幾個方法:
- (void)addElement:(elementType)anObj;
- (void)removeElement:(elementType)anObj;
- (NSArray *)elements;
- (void)addLayoutManager:(NSLayoutManager *)obj; - (void)removeLayoutManager:(NSLayoutManager *)obj; - (NSArray *)layoutManagers;
若集合是無序的,返回 NSSet 比 NSArray 更好;若需要在特定位置插入元素,可使用:
- (void)insertLayoutManager:(NSLayoutManager *)obj atIndex:(int)index; - (void)removeLayoutManagerAtIndex:(int)index;
參數名以小寫字母開始,之後單詞首字母大寫,如 removeObject:(id)anObject。
別用 pointer 或 ptr 命名,參數類型已表明它是否為指針。
避免只有一到兩個字母的參數名,也避免只有幾個字母的縮寫。
...action:(SEL)aSelector ...alignment:(int)mode ...atIndex:(int)index ...content:(NSRect)aRect ...doubleValue:(double)aDouble ...floatValue:(float)aFloat ...font:(NSFont *)fontObj ...frame:(NSRect)frameRect ...intValue:(int)anInt ...keyEquivalent:(NSString *)charCode ...length:(int)numBytes ...point:(NSPoint)aPoint ...stringValue:(NSString *)aString ...tag:(int)anInt ...target:(id)anObject ...title:(NSString *)aString
不要用下劃線作為私有方法的前綴,Apple 保留這一用法;若你的私有方法名已被 Apple 使用,覆蓋它將產生極難追蹤的 bug。如果繼承自大型 Cocoa 框架(如 UIView),請確保子類的私有方法名與父類不同。可為私有方法加一個前綴,如公司名或項目名:XX_。例如項目叫 Byte Flogger,前綴可能是 BF_addObject。總之,為子類私有方法添加前綴,是為了不覆蓋父類的私有方法。
函數的命名類似方法,但有兩點要注意:使用與類和常量相同的前綴;前綴後首字母大寫。許多函數名以描述其作用的動詞開始:
NSHighlightRect NSDeallocateObject
查詢屬性的函數有進一步的命名規則:若函數返回首個參數的屬性,省略動詞;若透過 reference 返回值,使用 Get;若返回 boolean 值,則靈活使用動詞。
unsigned int NSEventMaskFromType(NSEventType type) float NSHeight(NSRect aRect)
const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)
BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)
Property
Property 命名規則與第二章 accessor methods 相同(因為兩者緊密聯繫)。若 property 表示名詞或動詞:
@property (…) 類型 名詞/動詞;
@property (strong) NSString *title; @property (assign) BOOL showsAlpha;
若 property 表示形容詞,可省略 is 前綴,但要指定 getter 方法的慣用名稱:
@property (assign, getter=isEditable) BOOL editable;
實例變量
通常不應直接訪問實例變量,init、dealloc、accessor methods 等內部例外。實例變量以下劃線「_」開始,並確保它描述了所存儲的屬性。
@implementation MyClass {
BOOL _showsTitle;
}若想修改 property 的實例變量名,使用 @synthesize 語句:
@implementation MyClass @synthesize showsTitle=_showsTitle;
為一個 class 添加實例變量時需注意:避免聲明公有實例變量(開發者關注的應是對象接口,而非數據細節,可用 property 避免聲明實例變量);若需聲明,指定 @private 或 @protected(希望子類可直接訪問時用 @protected);若某實例變量是類可訪問的屬性,確保寫了 accessor methods,可能的話還是用 property。
枚舉常量
使用枚舉來關聯一組 integer 常量,枚舉常量和 typedef 遵循函數的命名規範:
typedef enum _NSMatrixMode {
NSRadioModeMatrix = 0,
NSHighlightModeMatrix = 1,
NSListModeMatrix = 2,
NSTrackModeMatrix = 3
} NSMatrixMode;你可以為 bit masks 之類的東西創建一個匿名枚舉:
enum {
NSBorderlessWindowMask = 0,
NSTitledWindowMask = 1 << 0,
NSClosableWindowMask = 1 << 1,
NSMiniaturizableWindowMask = 1 << 2,
NSResizableWindowMask = 1 << 3
};使用 const 關鍵字的常量
用 const 關鍵字來創建 float 常量;也可用 const 創建與其他常量不相關的 integer 常量,否則用枚舉。使用 const 的常量也遵循函數命名規則:
const float NSLightGray;
其他常量類型
通常不應使用 #define 創建常量:integer 常量用枚舉,float 常量用 const 修飾符。
對 #define 預編譯指令,大寫所有字母,比如 DEBUG 判斷。
注意宏命令的字首和字尾都有雙下劃線,如 __MACH__。
定義 NSString 常量作為 Notification 和 Key 值,可有效防止拼寫錯誤。
#ifdef DEBUG
APPKIT_EXTERN NSString *NSPrintCopies;
Notifications 格式:
[Name of associated class] + [Did | Will] + [UniquePartOfName] + Notification
NSApplicationDidBecomeActiveNotification NSWindowDidMiniaturizeNotification NSTextViewDidChangeSelectionNotification NSColorPanelColorDidChangeNotification
Exceptions 格式:
[Prefix] + [UniquePartOfName] + Exception
NSColorListIOException NSColorListNotEditableException NSDraggingException NSFontUnavailableException NSIllegalSelectorException
設計編程接口時通常不應使用縮寫,但下列已被廣泛使用的縮寫名稱除外:標準 C 庫中的縮寫名,如 alloc、init;參數名可自由使用縮寫,如 imageRep、col、obj、otherWin。

