[Cocoa][譯]蘋果 Cocoa 編碼規(guī)范中文版

羅朝輝(http://m.shnenglu.com/kesalin/)

CC許可，轉載請注明出處

> Code Naming Basics 代碼命名基礎

在面向對象軟件庫的設計過程中，開發(fā)人員經常忽視對類，方法，函數，常量以及其他編程接口元素的命名。本節(jié)討論大多數Cocoa接口的一些命名約定。

>> General Principles 一般性原則

>>> Clarity 清晰性

● 最好是既清晰又簡短，但不要為簡短而喪失清晰性

● 名稱通常不縮寫，即使名稱很長，也要拼寫完全

你可能會認為某個縮寫廣為人知，但有可能并非如此，尤其是當你的代碼被來自不同文化和語言背景的開發(fā)人員所使用時。

● 然而，你可以使用少數非常常見，歷史悠久的縮寫。請參考：”可接受的縮略名“一節(jié)

● 避免使用有歧義的 API 名稱，如那些能被理解成多種意思的方法名稱

>>> Consistency 一致性

● 盡可能使用與 Cocoa 編程接口命名保持一致的名稱。如果你不太確定某個命名的一致性，請瀏覽一下頭文件或參考文檔中的范例

● 在使用多態(tài)方法的類中，命名的一致性非常重要。在不同類中實現相同功能的方法應該具有相同的名稱

請參考“方法參數”一節(jié)。

>>> No Self Reference 不要自我指涉

● 不要名稱自我指涉

● 掩碼（可使用位操作進行組合）和用作通知名稱的常量不受該約定限制

>> Prefixes 前綴

前綴是名稱的重要組成部分。它們可以區(qū)分軟件的功能范疇。通常，軟件會被打包成一個框架或多個緊密相關的框架（如 Foundation 和 Application Kit 框架）。前綴可以防止第三方開發(fā)者與蘋果公司之間的命名沖突（同樣也可防止蘋果內部不同框架之間的命名沖突）

● 前綴有規(guī)定的格式。它由兩到三個大寫字符組成，不能使用下劃線與子前綴

● 命名 class，protocol，structure，函數，常量時使用前綴；命名成員方法時不使用前綴，因為方法已經在它所在類的命名空間種；同理，命名結構體字段時也不使用前綴

>> Typographic Conventions 書寫約定

在為 API 元素命名時，請遵循如下一些簡單的書寫約定

● 對于包含多個單詞的名稱，不要使用標點符號作為名稱的一部分或作為分隔符（下劃線，破折號等）；此外，大寫每個單詞的首字符并將這些單詞連續(xù)拼寫在一起。請注意以下限制：

• 方法名小寫第一個單詞的首字符，大寫后續(xù)所有單詞的首字符。方法名不使用前綴。如： fileExistsAtPath:isDirectory: 如果方法名以一個廣為人知的大寫首字母縮略詞開頭，該規(guī)則不適用，如：NSImage 中的 TIFFRepresentation
• 函數名和常量名使用與其關聯類相同的前綴，并且要大寫前綴后面所有單詞的首字符。如：NSRunAlertPanel，NSCellDisabled
• 避免使用下劃線來表示名稱的私有屬性。蘋果公司保留該方式的使用。如果第三方這樣使用可能會導致命名沖突，他們可能會在無意中用自己的方法覆蓋掉已有的私有方法，這會導致嚴重的后果。請參考“私有方法”一節(jié)以了解私有 API 的命名約定的建議

>> Class and Protocol Names 類與協議命名

類名應包含一個明確描述該類（或類的對象）是什么或做什么的名詞。類名要有合適的前綴（請參考“前綴”一節(jié)）。Foundation 及 Application Kit 有很多這樣例子，如：NSString, NSData, NSScanner, NSApplication, NSButton 以及 NSEvent。

協議應該根據對方法的行為分組方式來命名。

● 大多數協議僅組合一組相關的方法，而不關聯任何類，這種協議的命名應該使用動名詞(ing)，以不與類名混淆。

● 有些協議組合一些彼此無關的方法（這樣做是避免創(chuàng)建多個獨立的小協議）。這樣的協議傾向于與某個類關聯在一起，該類是協議的主要體現者。在這種情形，我們約定協議的名稱與該類同名。NSObject 協議就是這樣一個例子。這個協議組合一組彼此無關的方法，有用于查詢對象在其類層次中位置的方法，有使之能調用特殊方法的方法以及用于增減引用計數的方法。由于 NSObject 是這些方法的主要體現者，所以我們用類的名稱命名這個協議。

>> Header Files 頭文件

頭文件的命名方式很重要，我們可以根據其命名知曉頭文件的內容。

● 聲明孤立的類或協議：將孤立的類或協議聲明放置在單獨的頭文件中，該頭文件名稱與類或協議同名

● 聲明相關聯的類或協議：將相關聯的聲明（類，類別及協議) 放置在一個頭文件中，該頭文件名稱與主要的類/類別/協議的名字相同。

● 包含框架頭文件：每個框架應該包含一個與框架同名的頭文件，該頭文件包含該框架所有公開的頭文件。

● 為已有框架中的某個類擴展 API：如果要在一個框架中聲明屬于另一個框架某個類的范疇類的方法，該頭文件的命名形式為：原類名+“Additions”。如 Application Kit 中的 NSBundleAdditions.h 

● 相關聯的函數與數據類型：將相聯的函數，常量，結構體以及其他數據類型放置到一個頭文件中，并以合適的名字命名。如 Application Kit 中的 NSGraphics.h

> Naming Methods 方法命名

>> General Rules 一般性規(guī)則

為方法命名時，請考慮如下一些一般性規(guī)則：

● 小寫第一個單詞的首字符，大寫隨后單詞的首字符，不使用前綴。請參考“書寫約定”一節(jié)。有兩種例外情況：1，方法名以廣為人知的大寫字母縮略詞（如TIFF or PDF）開頭；2，私有方法可以使用統一的前綴來分組和辨識，請參考“私有方法”一節(jié)

● 表示對象行為的方法，名稱以動詞開頭：

- (void) invokeWithTarget:(id)target:

- (void) selectTabViewItem:(NSTableViewItem *)tableViewItem

名稱中不要出現 do 或 does，因為這些助動詞沒什么實際意義。也不要在動詞前使用副詞或形容詞修飾

● 如果方法返回方法接收者的某個屬性，直接用屬性名稱命名。不要使用 get，除非是間接返回一個或多個值。請參考“訪問方法”一節(jié)。

● 參數要用描述該參數的關鍵字命名

● 參數前面的單詞要能描述該參數。

● 細化基類中的已有方法：創(chuàng)建一個新方法，其名稱是在被細化方法名稱后面追加參數關鍵詞

● 不要使用 and 來連接用屬性作參數關鍵字

雖然上面的例子中使用 add 看起來也不錯，但當你方法有太多參數關鍵字時就有問題。

● 如果方法描述兩種獨立的行為，使用 and 來串接它們

>> Accessor Methods 訪問方法

訪問方法是對象屬性的讀取與設置方法。其命名有特定的格式依賴于屬性的描述內容。

● 如果屬性是用名詞描述的，則命名格式為：

- (void) setNoun:(type)aNoun;

- (type) noun;

例如：

- (void) setgColor:(NSColor *)aColor;

- (NSColor *) color;

● 如果屬性是用形容詞描述的，則命名格式為：

- (void) setAdjective:(BOOL)flag;

- (BOOL) isAdjective;

例如：

- (void) setEditable:(BOOL)flag;

- (BOOL) isEditable;

● 如果屬性是用動詞描述的，則命名格式為：（動詞要用現在時時態(tài)）

- (void) setVerbObject:(BOOL)flag;

- (BOOL) verbObject;

例如：

- (void) setShowAlpha:(BOOL)flag;

- (BOOL) showsAlpha;

● 不要使用動詞的過去分詞形式作形容詞使用

● 可以使用情態(tài)動詞（can, should, will 等）來提高清晰性，但不要使用 do 或 does

● 只有在方法需要間接返回多個值的情況下，才使用 get

像上面這樣的方法，在其實現里應允許接受 NULL 作為其 in/out 參數，以表示調用者對一個或多個返回值不感興趣。

>> Delegate Methods 委托方法

委托方法是那些在特定事件發(fā)生時可被對象調用，并聲明在對象的委托類中的方法。它們有獨特的命名約定，這些命名約定同樣也適用于對象的數據源方法。

● 名稱以標示發(fā)送消息的對象的類名開頭，省略類名的前綴并小寫類第一個字符

● 冒號緊跟在類名之后（隨后的那個參數表示委派的對象）。該規(guī)則不適用于只有一個 sender 參數的方法

● 上面的那條規(guī)則也不適用于響應通知的方法。在這種情況下，方法的唯一參數表示通知對象

● 用于通知委托對象操作即將發(fā)生或已經發(fā)生的方法名中要使用 did 或 will

● 用于詢問委托對象可否執(zhí)行某操作的方法名中可使用 did 或 will，但最好使用 should 

>> Collection Methods 集合方法

管理對象（集合中的對象被稱之為元素）的集合類，約定要具備如下形式的方法：

例如：

集合方法命名有如下一些限制和約定：

● 如果集合中的元素無序，返回 NSSet，而不是 NSArray 

● 如果將元素插入指定位置的功能很重要，則需具備如下方法：

集合方法的實現要考慮如下細節(jié)：

● 以上集合類方法通常負責管理元素的所有者關系，在 add 或 insert 的實現代碼里會 retain 元素，在 remove 的實現代碼中會 release 元素

● 當被插入的對象需要持有指向集合對象的指針時，通常使用 set... 來命名其設置該指針的方法，且不要 retain 集合對象。比如上面的 insertLayerManager:atIndex: 這種情形，NSLayoutManager 類使用如下方法：

通常你不會直接調用 setTextStorage:，而是覆寫它。

另一個關于集合約定的例子來自 NSWindow 類：

>> Method Arguments 方法參數

命名方法參數時要考慮如下規(guī)則：

● 如同方法名，參數名小寫第一個單詞的首字符，大寫后繼單詞的首字符。如：removeObject:(id)anObject

● 不要在參數名中使用 pointer 或 ptr，讓參數的類型來說明它是指針

● 避免使用 one， two，...，作為參數名

● 避免為節(jié)省幾個字符而縮寫 

按照 Cocoa 慣例，以下關鍵字與參數聯合使用：

>> Private Methods 私有方法

大多數情況下，私有方法命名相同與公共方法命名約定相同，但通常我們約定給私有方法添加前綴，以便與公共方法區(qū)分開來。即使這樣，私有方法的名稱很容易導致特別的問題。當你設計一個繼承自 Cocoa framework 某個類的子類時，你無法知道你的私有方法是否不小心覆蓋了框架中基類的同名方法。

Cocoa framework 的私有方法名稱通常以下劃線作為前綴（如：_fooData），以標示其私有屬性。基于這樣的事實，遵循以下兩條建議：

● 不要使用下劃線作為你自己的私有方法名稱的前綴，Apple 保留這種用法。

● 若要繼承 Cocoa framework 中一個超大的類（如：NSView），并且想要使你的私有方法名稱與基類中的區(qū)別開來，你可以為你的私有方法名稱添加你自己的前綴。這個前綴應該具有唯一性，如基于你公司的名稱，或工程的名稱，并以“XX_”形式給出。比如你的工程名為"Byte Flogger"，那么就可以是“BF_addObject:”

盡管為私有方法名稱添加前綴的建議與前面類中方法命名的約定沖突，這里的意圖有所不同：為了防止不小心地覆蓋基類中的私有方法。

> Naming Functions 函數命名

Objective-C 允許通過函數（C形式的函數）描述行為，就如成員方法一樣。 你應當優(yōu)先使用函數，而不是類方法，如果隱含的類為單例或在處理函數子系統時。

函數命名應該遵循如下幾條規(guī)則：

● 函數命名與方法命名相似，但有幾點不同：

• 它們有前綴，其前綴與你使用的類和常量的前綴相同
• 大寫前綴后緊跟的第一個單詞首字符

● 大多數函數名稱以動詞開頭，這個動詞描述該函數的行為

查詢屬性的函數有個更多的規(guī)則要遵循：

● 查詢第一個參數的屬性的函數，省略動詞

● 返回值為引用的方法，使用 Get

● 返回 boolean 值的函數，名稱使用判斷動詞 is/does 開頭 

> Naming Instance Variables and Data Types 實例變量與數據類型命名

這一節(jié)描述實例變量，常量，異常以及通知的命名約定。

>> Instance Variables 實例變量

在為類添加實例變量是要注意：

● 避免創(chuàng)建 public 實例變量

● 使用 @private，@protected 顯式限定實例變量的訪問權限

● 確保實例變量名簡明扼要地描述了它所代表的屬性

如果實例變量別設計為可被訪問的，確保編寫了訪問方法

>> Constants 常量

常量命名規(guī)則根據常量創(chuàng)建的方式不同而大不同。

>>> 枚舉常量

● 使用枚舉來定義一組相關的整數常量

● 枚舉常量與其 typedef 命名遵守函數命名規(guī)則。如：來自 NSMatrix.h 中的例子：（本例中的 typedef tag（_NSMatrixMode）不是必須的）

typedef enum _NSMatrixMode {

    NSRadioModeMatrix       = 0,

    NSHighlightModeMatrix = 1;

    NSListModeMatrix           = 2,

    NSTrackModeMatrix        = 3

} NSMatrixMode;

● 位掩碼常量可以使用不具名枚舉。如：

enum {

    NSBorderlessWindowMask         = 0,

    NSTitledWindowMask                 = 1 << 0,

    NSClosableWindowMask            = 1 << 1,

    NSMiniaturizableWindowMask  = 1 << 2,

    NSResizableWindowMask          = 1 << 3

};

>>> const 常量

● 使用 const 來修飾浮點常量或彼此沒有關聯的整數常量 

● 枚舉常量命名規(guī)則與函數命名規(guī)則相同。const 常量命名范例：

>>> 其他常量

● 通常不使用 #define 來創(chuàng)建常量。如上面所述，整數常量請使用枚舉，浮點數常量請使用 const

● 使用大寫字母來定義預處理編譯宏。如：#ifdef DEBUG

● 編譯器定義的宏名首尾都有雙下劃線。如：__MACH__

● 為 notification 名及 dictionary key 定義字符串常量，從而能夠利用編譯器的拼寫檢查，減少書寫錯誤。Cocoa  框架提供了很多這樣的范例：

實際的字符串值在實現文件中賦予。（注意：APPKIT_EXTERN 宏等價于Objective-C 中 extern）

>> Exceptions and Notifications 異常與通知

異常與通知的命名遵循相似的規(guī)則，但是它們有各自推薦的使用模式。

>>> 異常

雖然你可以處于任何目的而使用異常（由 NSException 類及相關類實現），Cocoa 通常不使用異常來處理常規(guī)的，可預料的錯誤。在這些情形下，使用諸如 nil, NULL, NO或錯誤代碼之類的返回值。異常的典型應用類似數組越界之類的編程錯誤。

異常由具有如下形式的全局 NSString 對象標識：

[Prefix] + UniquePartOfName + Exception

UniquePartOfName 部分是有連續(xù)的首字符大寫的單詞組成。例如：

>>> 通知

如果一個類有委托，那它的大部分通知可能由其委托的委托方法來處理。這些通知的名稱應該能夠反應其響應的委托方法。比如，當應用程序提交 NSApplicationDidBecomeActiveNotification 通知時，全局 NSApplication 對象的委托會注冊從而能夠接收 applicaitonDidBecomeActive: 消息。

通知由具有如下形式的全局 NSString 對象標識：

[相關聯類的名稱] + [Did 或 Will] + [UniquePartOfName] + Notification

例如：

> 可接受的縮略語

在設計編程接口時，通常名稱不要縮寫。然而，下面列出的縮寫要么是固定下來的要么是過去被廣泛使用的，所以你可以繼續(xù)使用。關于縮寫有一些額外的注意事項：

● 標準 C 庫中長期使用的縮寫形式是可以接受的。如："alloc"，"getc"

● 你可以在參數名中更自由地使用縮寫。如：imageRep，col（column），obj，otherWin

常見的縮寫

常見的縮寫：

> 框架開發(fā)者小貼士與技巧

>> Initialize 初始化 

>>> 類初始化

在 initialize 類方法中，能夠編寫實現一些延遲執(zhí)行且只被一次的代碼，initialize 類方法是由運行時系統在該類響應任何其他消息之前調用的。典型的應用是在其中設置類的版本信息。運行時系統向每個類發(fā)送 initialize 消息，即使該類沒有實現 initialize，也會調用其基類的某個 initialize 方法。因此一個類的 initialize 方法可能會因為存在繼承類的緣故被執(zhí)行多次。因此有必要使用一定的技巧來防止只執(zhí)行一次的代碼被多次執(zhí)行。如：NSFoo 類的 initialize 方法實現可能如下：

+ (id) initialize

{

    if (self == [NSFoo class])

    {

        // 初始化代碼

    }

    return self;

}
不應當顯式調用 initialize 方法。如果你需要激活 initialize 方法，使用 [NSFoo self] 形式的調用。

Ref：
Coding Guidelines for Cocoa