這是一篇翻譯版，英文版來自apple的官方文檔：
Coding Guidelines for Cocoa

介紹

Cocoa編程指南介紹

通過公開API開發Cocoa框架，插件，或者其他可執行文件需要一些不同于開發應用程序的方式和約定。開發者是你的產品的主要客戶，并且讓他們沒有對你的編程接口感到困惑是非常重要的。這就是API命名約定派上用場，這會有助于你的接口保持一致和清晰。還有些編程技術對于這個框架來說是比較特殊的或者說更加重要，例如版本控制，二進制兼容性，錯誤處理和內存管理。本專題包含Cocoa命名規范和推薦的框架編程實踐。

文檔組織結構

本專題所包含的文章分為兩類。第一部分和大部分的模塊給出了對編程接口的命名規范。apple在自身的Cocoa框架中也使用這些命名規范。這些關于命名規范的包含如下內容：

1. 代碼命名基礎 2. 方法的命名 3. 函數的命名 4. 屬性和數據類型的命名 5. 可接受的簡寫和縮寫

第二部分(當前只有一個成員)討論框架開發的各個方面

框架開發的小技巧

代碼命名基礎

類，方法，函數，常量和其他編程接口的元素經常在面向對象編程軟件設計被忽視。該部分介紹了許多在cocoa接口中實現的命名規范。

基本原則

清晰
- 盡量保持清楚和簡潔很好，但是命名清晰比簡潔更重要。

CodeCommentary

insertObject:atIndex:	好
insert:at:	不清晰；插入什么？“at”表示什么？atNot clear;what is being inserted?what does “at”signify?
revmoveObjectAtIndext:	好
removeObject:	好，因為刪除作為參數的對象。
remove:	不明確，刪除什么？

- 通常，不要縮寫名字。即使它們很長也要拼寫出來。

代 碼評 價

destinationSelection:	好
destSel	不清晰
setBackgroundColor：	好
setBkgColor:	不清晰

你可能認為縮寫是眾所周知的，但它可能不是，特別是有不同的文化和語言背景開發者遇到你的方法和函數。
- 然而，有少數的縮寫確實是通用的并且用了很長時間。可以繼續使用，查看Acceptable Abbreviations and Acronyms.
- 避免API命名不明確，例如方法名稱可能被解釋為多種含義。

代碼評論

sendPort	是發送端口還是返回端口？
displayName	在用戶界面中顯示一個名字還是返回接受者的標題 ？

一致性
- 嘗試保持在Cocoa編程接口上的命名一致性。如果不確定，請查閱現在的頭文件或者之前的參看文件。
- 當一個類中的許多方法有多態性的時候，一致性是非常重要的。這些方法在不同的類中使用同樣的名稱做同樣的操作。

代 碼評 論

(NSInteger)tag	定義在NSView,NSCell,NSControl.
(void)setStringValue:(NSString *)	在許多Cocoa類中有定義

也可參照：Method Arguments

不要自我引用

• 命名不應該自我引用

代碼評論

NSString	可以
NSStringObject	自我引用

- 作為掩碼的一些常量（可以按位與進行合并），這些常量常量一般不使用這種規則，例如作為通知名稱的常量.

代碼評論

NSUnderlineByWordMask	可以
NSTableViewColumnDidMoveNotification	可以

前綴

書寫約定

下面有幾個簡單的命名API的書寫規范
- 名字有多個單詞組成，不要使用下劃線，破折號或者其他符號分割。使用駝峰命名法
對于方法命名，以小寫字母開頭，后面的單詞首字母大寫。不要使用前綴。

fileExistsAtPath:isDirectory:

• 函數和常量的命名，對于相關的類使用同樣的前綴并且首字母大寫以及后邊的單詞

NSRunAlertPanelNSCellDisabled

• 避免使用下劃線作為前綴

類和協議的命名

類的名稱應該包含一個清晰的表達出該類的意義。類名應該有一個前綴。Foundation和許多應用程序框架都是一些案例。例如NSString，NSData,NSScanner,NSApplication …和UIButton。

Protocol 應該根據它所組成的一些行為事件來命名。
- 大多數的協議與包含的一些方法有關系而與某種類沒有關系。這種協議應該避免與類名混淆。通常約定用一種動名詞(“…ing”)的格式.

代 碼評論

NSLocking	好
NSLock	差（看起來像一個類名）

- 一些協議包含許多沒有關系的方法（而不是創建很多分離的小的協議）。這些協議與某個類有關系，這個類是這些協議的主要表現。在這種情況下，應該約定將協議和類命名一致。

NSObject協議就是這種類型的協議。

頭文件

方法命名

方法的命名也許是編程接口中最普通的元素，因此應該在命名過程中需要特別注意。這部分討論方法命名的如下幾個方面：

基本規則

通常有如下幾項規則：
- 小寫字母開頭，大寫包含的英文單詞的首字母。不要使用前綴
- 對于表示操作于某個對象的方法，方法的命名以動詞開頭：

- (void)invokeWithTarget:(id)target;- (void)selectTabViewItem:(NSTabViewItem *)tabViewItem;

不要使用“do” 或者 “does” 作為名字的一部分因為這些助動詞幾乎沒有任何意義。并且，不要在動詞前面使用副詞或者形容詞。
- 如果某個方法返回調用者的某個屬性，直接在屬性后面命名就可以。不要使用“get”，除非需要直接返回一個或者多個值。

代碼評論

(NSSize)cellSize;	正確
(NSSize)calcCellSize:	錯誤
(NSSize)getCellSize;	錯誤

- 在參數前面使用關鍵字

代碼評價

(void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag;	正確
(void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;	錯誤

- 在參數前面描述參數

代碼評價

(id)viewWithTag:(NSInteger)aTag;	正確
(id)taggedView:(int)aTag;	錯誤

- 當創建一個比繼承的方法更加明確的方法的時候，需要添加新的關鍵字在已經存在的方法后面。

代碼評價

(id)initWithFrame:(CGRect)frameRect;	NSView, UIView.
(id)initWithFrame:(NSRect)frameRect mode:(int)aMode cellClass:(Class)factoryId numberOfRows:(int)rowsHigh numberOfColumns:(int)colsWide;	NSMatrix, a subclass of NSView

- 不要使用“and”連接是調用者屬性的關鍵字。

代碼評價

(int)runModalForDirectory:(NSString )path file:(NSString ) name types:(NSArray *)fileTypes;	正確
(int)runModalForDirectory:(NSString )path andFile:(NSString )name andTypes:(NSArray *)fileTypes;	錯誤

- 如果方法有兩種不同的行為，使用“and”連接它們。

代碼評價

(BOOL)openFile:(NSString )fullPath withApplication:(NSString )appName andDeactivate:(BOOL)flag;	NSWorkspace

訪問器方法

訪問器方法是一個設置和讀取對象的屬性值得方法。根據屬性的表達方式擁有某種推薦的方式。
- 一個屬性表示一個名詞，格式是：

- (type)noun； - (void)setNoun:(type)aNoun;

舉例：

- (NSString *)title;- (void)setTitle:(NSString *)aTitle;

• 一個屬性表示形容詞，格式是：

- (BOOL)isAdjective;- (void)setAdjective:(BOOL)flag;

舉例：

- (BOOL)isEditable;- (void)setEditable:(BOOL)flag;

• 屬性表示動詞，格式是：

- (BOOL)verbObject;- (void)setVerbObject:(BOOL)flag;

舉例：

- (BOOL)showsAlpha;- (void)setShowsAlpha:(BOOL)flag;

動詞應該使用現在時
- 不要將動詞通過介詞轉為形容詞

代碼評論

(void)setAcceptsGlyphInfo:(BOOL)flag;	正確
(BOOL)acceptsGlyphInfo;	正確
(void)setGlyphInfoAccepted:(BOOL)flag;	錯誤
(BOOL)glyphInfoAccepted;	錯誤

- 可以使用情態動詞(在動詞前面加 “can”，“should”，“will”等等)澄清含義，但是不要使用“do”或者“does”

代碼評論

(void)setCanHide:(BOOL)flag;	正確
(void)setCanHide:(BOOL)flag;	正確
(void)setShouldCloseDocument:(BOOL)flag;	正確
(BOOL)shouldCloseDocument;	正確
(void)setDoesAcceptGlyphInfo:(BOOL)flag;	錯誤
(BOOL)doesAcceptGlyphInfo;	錯誤

- 只有在間接返回對象和值的方法中才使用“get”，只有需要返回多個值得的方法菜需要使用這種格式。

代碼用處

(void)getLineDash:(float )pattern count:(int )count phase:(float *)phase;	NSBezierPath.

代理方法

代理方法是對象能夠在其代理中喚醒調用當某種事件發生的時候。它們有一種特殊的形式，這種形式同樣適用于一個對象數據源的方法中。
- 以表示發送消息的對象所屬類來命名開頭

- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row; - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;

該類的名字省略了前綴并且以小寫字母開頭。

• 冒號在類名后面（對于代理對象來說參數是一個引用）除非方法只有一個參數，這個參數就是消息發送者。

- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

• 有一種例外就是消息通知發送的消息。這種情況下，唯一的參數是通知對象。

- (void)windowDidChangeScreen:(NSNotification *)notification;

• 代理方法使用“did”或者“will”通知代理已經發生了或者將要發生什么？

- (void)browserDidScroll:(NSBrowser *)sender; - (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;

• 盡管代理方法可以使用“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;

需要記憶的一些集合方法的細節

• 這些方法需要代表與操作對象這件的所屬關系，添加或者插入需要持有該對象，刪除必須釋放該對象。

對于上面的規范有一些自于NSWindow類的集合方法

- (void)addChildWindow:(NSWindow *)childWin ordered:(NSWindowOrderingMode)place; - (void)removeChildWindow:(NSWindow *)childWin; - (NSArray *)childWindows; - (NSWindow *)parentWindow; - (void)setParentWindow:(NSWindow *)window;

方法參數

私有方法

有兩條建議
- 不要使用下劃線開頭，apple在使用。
- 如果子類化一個Cocoa框架類，可以使用公司或者工程名稱作為前綴如“XX_”。如果你的項目為:Byte Flogger,前綴是BF_addObject;

函數命名

函數有些需要遵守的規則
- 函數命名如方法的命名很相像，但是有一些例外需要注意

1.使用在常量和類中使用的前綴2.在前綴后的首字母大寫

• 大部分函數以描述函數意義的動詞開頭

NSHighlightRectNSDeallocateObjec

查詢屬性的函數有更多的一些規則
- 如果函數返回其第一個參數的屬性，需要省略動詞。

unsigned int NSEventMaskFromType(NSEventType type)float NSHeight(NSRect aRect)

• 如果通過引用返回其值，使用“get”

const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)

• 如果返回一個boolean值，應該以一個變形的動詞開頭

BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)

屬性和數據類型命名

聲明屬性和實例變量

如果屬性或者實例變量是名字和動詞，格式如下：
@property(__)type nounOrVerb;

舉例

@property (strong) NSString *title; @property (assign) BOOL showsAlpha;

如果屬性或者變量是形容詞，但是需要省略“is”前綴，但是需要詳細的約定獲取方法，例如：

@property (assgin,getter=isEditable) Bool editable;

許多情況下，當使用一個已經聲明的屬性也應該合成相應的實例變量。
確保實例變量的名字簡潔地描述存儲屬性。通常你不應該直接訪問實例變量。應該通過訪問方法來訪問。為了有助于標志實例變量，可以使用下劃線開頭，例如：

@implementation MyClass {BOOL _showsTitle; }

如果使用一個已經聲明的屬性來合成實例變量，在@synthesize語句中詳細說明實例變量。

@implementation MyClass @synthesize showsTitle=_showsTitle;

一些注意事項
- 不要顯示的聲明一個公開的實例變量
- 如果需要聲明一個實例變量，明確聲明是@private 或者@protected
- 如果一個實例變量一個可訪問的實例屬性，確保為這個實例變量編寫了訪問器方法

常量

常量根據創建方式的不同，規則也不一樣。

枚舉常量

typedef enum _NSMatrixMode {NSRadioModeMatrix = 0,NSHighlightModeMatrix = 1,NSListModeMatrix = 2,NSTrackModeMatrix = 3 } NSMatrixMode;

使用const創建常量

使用const的例子

const float NSLightGray;

其他類型的常量

• 通常，不要使用#define預處理器命令來創建常量。
• 使用大寫，舉例

#ifdef DEBUG

• 注意，編譯器定義的宏前后都有兩個下劃線，舉例：

__MACH__

通知和異常

通知和異常的命名也是類似的規則。但是兩者都有它們推薦的使用方式。

通知

如果一個類有代理，那么代理會通過事先定義好的代理方法來接受大多數的通知。這些通知名稱應該反映相應的代理方法。例如,全局的NSApplication對象的自動注冊的代理會接受applicationDidBecomeActive:的消息當app發送一個NSApplicationDidBecomeActiveNotification的通知。

通知使用NSString來表示，使用下面的方式來命名：

[Name of associated class] + [Did | Will] + [UniquePartOfName] + Notification

例如:

NSApplicationDidBecomeActiveNotificationNSWindowDidMiniaturizeNotificationNSTextViewDidChangeSelectionNotificationNSColorPanelColorDidChangeNotification

異常

使用全局的NSString對象來表示異常，命名組成如下：

[Prefix] + [UniquePartOfName] + Exception

Unique 部分應該將單詞組成在一塊并且大寫每一個單詞的首字母。下面一些例子：

NSColorListIOExceptionNSColorListNotEditableExceptionNSDraggingExceptionNSFontUnavailableExceptionNSIllegalSelectorException

可接受的簡寫和縮寫

通常，不應該對接口的名稱進行縮寫。然而，下面列出的縮寫已經被創建或者在過去被使用了很久，因此，可以繼續使用。關于縮寫有一些其他需要注意的地方：
- 來源于標準C庫的一些縮寫，例如‘alloc’和‘getc’是被允許的。
- 在參數的命名中可以更加自由的使用縮寫。

AbbreviationMeaning and comments

alloc	Allocate
alt	Alternate
app	Application. For example, NSApp the global application object. However, “application” is spelled out in delegate methods, notifications, and so on.
calc	Calculate
dealloc	Deallocate.
func	Function.
horiz	Horizontal.
info	Information.
init	Initialize (for methods that initialize new objects).
int	Integer (in the context of a C int—for an NSInteger value, use integer).
max	Maximum.
min	Minimum.
msg	Message.
nib	Interface Builder archive.
pboard	Pasteboard (but only in constants).
rect	Rectangle.
Rep	Representation (used in class name such as NSBitmapImageRep).
temp	Temporary.
vert	Vertical.

在計算機產業中使用的縮寫和首字母縮略詞你可能使用到，下面有些熟知的縮略詞：

ASCII

PDF

XML

HTML

URL

RTF

HTTP

TIFF

JPG

PNG

GIF

LZW

ROM

RGB

CMYK

MIDI

FTP

對于框架開發者的小技巧

這部分是關于框架開發者的一些建議，略…

總結

以上是生活随笔為你收集整理的Cocoa编程指南的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。