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

[iOS 翻譯] Cocoa 編碼規範:打造團隊協作的一致性代碼

編輯:iOS 開發基礎

簡介:

本文整理自 Apple 文件《Coding Guidelines for Cocoa》。這份文件原意是為 Cocoa 框架、外掛及公共 API 開發者提供編碼指導,實質上相當於 Apple 內部的編碼規範。在多人協作時,一份統一的代碼規範能大幅降低開發者之間的溝通成本,特此大力推薦。

目錄:

一、代碼命名基礎;二、方法;三、函數;四、Property 及其他;五、縮寫。

一、代碼命名基礎

1. 通用原則

1.1 清晰

命名要盡量清晰又簡潔,無法兩全時,清晰永遠優先。

通常不應縮寫名稱,即使方法名很長也應完整拼寫。

  • 你可能認為某個縮寫眾所周知,但其實未必,尤其是當團隊成員語言文化背景各異時。

  • 少數歷史悠久的縮寫仍可沿用,詳見第五章。

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

1.2 一致

盡力保持 Cocoa 編程接口命名一致。

  • 若有疑惑,請瀏覽當前頭文件或參考文件。

當某個類別的方法使用多態時,一致性尤其重要。

  • 不同類別裡,功能相同的方法命名也應相同。

1.3 避免自引用(self Reference)

命名不應自引用,這裡的自引用指的是在詞尾引用自身。

Mask 與 Notification 可忽略此規則。

2. 前綴

前綴是編程接口命名的重要部分,它們區分了軟體的不同功能區域:

  • 前綴可防止第三方開發者與 Apple 的命名衝突,也能避免 Apple 內部的命名衝突。

  • 前綴有指定格式:由二到三個大寫字母組成,不使用下劃線與子前綴。

  • 命名類別、協議、函數、常量和 typedef 結構體時使用前綴;方法名不使用前綴(因為它存在於特定類別的命名空間中),結構體欄位也不使用前綴。

3. 書寫約定

命名 API 元素時,使用駝峰命名法(如 runTheWordsTogether),並注意以下約定:

方法名

  • 小寫第一個字母,大寫之後所有單詞的首字母,不加前綴。

  • 若方法名以眾所周知的大寫縮略詞開頭(如 TIFFRepresentation),此規則不適用。

fileExistsAtPath:isDirectory:

函數及常量名

  • 使用與其關聯類別相同的前綴,並大寫首字母。

NSRunAlertPanel
NSCellDisabled

標點符號

  • 由多個單詞組成的名稱,別把標點符號作為名稱的一部分,分隔符(下劃線、破折號等)也不能使用。

  • 避免使用下劃線作為私有方法的前綴,Apple 保留這一用法;強行使用可能導致命名衝突,覆蓋 Apple 既有方法,後果不堪設想。實例變量使用下劃線前綴則是允許的。

4. class 與 protocol 命名

class

  • class 的名稱應包含一個名詞,用以表明這個類別是什麼(或做了什麼),並擁有合適的前綴,如 NSString、NSDate、NSScanner、UIApplication、UIButton。

不關聯 class 的 protocol

  • 大多數 protocol 聚集了一堆相關方法,並不關聯 class;這類 protocol 使用 ing 形式以與 class 區分開來。

關聯 class 的 protocol

  • 一些 protocol 聚集了一堆無關方法,並試圖與某個 class 關聯,由這個 class 主導;這種 protocol 與 class 同名,如 NSObject protocol。

5. 頭文件

頭文件的命名極其重要,因為它能指出頭文件包含的內容:

  • 聲明一個孤立的 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。

二、方法

1. 通用原則

  • 以小寫字母開始,之後單詞首字母大寫;以眾所周知的縮寫開始時可大寫,如 TIFF、PDF;私有方法可加前綴。

  • 若方法代表對象接收的動作,以動詞開始,不要使用 do 或 does(助動詞在此少有實際意義),也不要在動詞前使用副詞和形容詞。

- (void)invokeWithTarget:(id)target;
- (void)selectTabViewItem:(NSTabViewItem *)tabViewItem
  • 若方法返回接收者的屬性,以「接收者 + 屬性」命名;除非間接返回多個值,否則不要使用 get(以與 accessor methods 區分)。

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

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

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

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

2. getter 和 setter 方法(Accessor Methods)

若 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,因為調用者未必對每個參數都感興趣。

3. Delegate 方法

以發送消息的對象開始(省略前綴的類名並小寫首字母):

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

4. 集合方法

為了管理集合中的元素,集合應有這幾個方法:

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

5. 方法參數

  • 參數名以小寫字母開始,之後單詞首字母大寫,如 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

6. 私有方法

不要用下劃線作為私有方法的前綴,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 及其他

1. Property 與實例變量

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。

2. 常量

枚舉常量

使用枚舉來關聯一組 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;

3. Notifications 與 Exceptions

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。

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