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

介紹

Cocoa編程指南介紹

通過(guò)公開(kāi)API開(kāi)發(fā)Cocoa框架，插件，或者其他可執(zhí)行文件需要一些不同于開(kāi)發(fā)應(yīng)用程序的方式和約定。開(kāi)發(fā)者是你的產(chǎn)品的主要客戶，并且讓他們沒(méi)有對(duì)你的編程接口感到困惑是非常重要的。這就是API命名約定派上用場(chǎng)，這會(huì)有助于你的接口保持一致和清晰。還有些編程技術(shù)對(duì)于這個(gè)框架來(lái)說(shuō)是比較特殊的或者說(shuō)更加重要，例如版本控制，二進(jìn)制兼容性，錯(cuò)誤處理和內(nèi)存管理。本專題包含Cocoa命名規(guī)范和推薦的框架編程實(shí)踐。

文檔組織結(jié)構(gòu)

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

1. 代碼命名基礎(chǔ) 2. 方法的命名 3. 函數(shù)的命名 4. 屬性和數(shù)據(jù)類型的命名 5. 可接受的簡(jiǎn)寫和縮寫

第二部分(當(dāng)前只有一個(gè)成員)討論框架開(kāi)發(fā)的各個(gè)方面

框架開(kāi)發(fā)的小技巧

代碼命名基礎(chǔ)

類，方法，函數(shù)，常量和其他編程接口的元素經(jīng)常在面向?qū)ο缶幊誊浖O(shè)計(jì)被忽視。該部分介紹了許多在cocoa接口中實(shí)現(xiàn)的命名規(guī)范。

基本原則

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

CodeCommentary

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

- 通常，不要縮寫名字。即使它們很長(zhǎng)也要拼寫出來(lái)。

代 碼評(píng) 價(jià)

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

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

代碼評(píng)論

sendPort	是發(fā)送端口還是返回端口？
displayName	在用戶界面中顯示一個(gè)名字還是返回接受者的標(biāo)題 ？

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

代 碼評(píng) 論

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

也可參照：Method Arguments

不要自我引用

• 命名不應(yīng)該自我引用

代碼評(píng)論

NSString	可以
NSStringObject	自我引用

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

代碼評(píng)論

NSUnderlineByWordMask	可以
NSTableViewColumnDidMoveNotification	可以

前綴

書寫約定

下面有幾個(gè)簡(jiǎn)單的命名API的書寫規(guī)范
- 名字有多個(gè)單詞組成，不要使用下劃線，破折號(hào)或者其他符號(hào)分割。使用駝峰命名法
對(duì)于方法命名，以小寫字母開(kāi)頭，后面的單詞首字母大寫。不要使用前綴。

fileExistsAtPath:isDirectory:

• 函數(shù)和常量的命名，對(duì)于相關(guān)的類使用同樣的前綴并且首字母大寫以及后邊的單詞

NSRunAlertPanelNSCellDisabled

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

類和協(xié)議的命名

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

Protocol 應(yīng)該根據(jù)它所組成的一些行為事件來(lái)命名。
- 大多數(shù)的協(xié)議與包含的一些方法有關(guān)系而與某種類沒(méi)有關(guān)系。這種協(xié)議應(yīng)該避免與類名混淆。通常約定用一種動(dòng)名詞(“…ing”)的格式.

代 碼評(píng)論

NSLocking	好
NSLock	差（看起來(lái)像一個(gè)類名）

- 一些協(xié)議包含許多沒(méi)有關(guān)系的方法（而不是創(chuàng)建很多分離的小的協(xié)議）。這些協(xié)議與某個(gè)類有關(guān)系，這個(gè)類是這些協(xié)議的主要表現(xiàn)。在這種情況下，應(yīng)該約定將協(xié)議和類命名一致。

NSObject協(xié)議就是這種類型的協(xié)議。

頭文件

方法命名

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

基本規(guī)則

通常有如下幾項(xiàng)規(guī)則：
- 小寫字母開(kāi)頭，大寫包含的英文單詞的首字母。不要使用前綴
- 對(duì)于表示操作于某個(gè)對(duì)象的方法，方法的命名以動(dòng)詞開(kāi)頭：

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

不要使用“do” 或者 “does” 作為名字的一部分因?yàn)檫@些助動(dòng)詞幾乎沒(méi)有任何意義。并且，不要在動(dòng)詞前面使用副詞或者形容詞。
- 如果某個(gè)方法返回調(diào)用者的某個(gè)屬性，直接在屬性后面命名就可以。不要使用“get”，除非需要直接返回一個(gè)或者多個(gè)值。

代碼評(píng)論

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

- 在參數(shù)前面使用關(guān)鍵字

代碼評(píng)價(jià)

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

- 在參數(shù)前面描述參數(shù)

代碼評(píng)價(jià)

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

- 當(dāng)創(chuàng)建一個(gè)比繼承的方法更加明確的方法的時(shí)候，需要添加新的關(guān)鍵字在已經(jīng)存在的方法后面。

代碼評(píng)價(jià)

(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”連接是調(diào)用者屬性的關(guān)鍵字。

代碼評(píng)價(jià)

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

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

代碼評(píng)價(jià)

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

訪問(wèn)器方法

訪問(wèn)器方法是一個(gè)設(shè)置和讀取對(duì)象的屬性值得方法。根據(jù)屬性的表達(dá)方式擁有某種推薦的方式。
- 一個(gè)屬性表示一個(gè)名詞，格式是：

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

舉例：

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

• 一個(gè)屬性表示形容詞，格式是：

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

舉例：

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

• 屬性表示動(dòng)詞，格式是：

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

舉例：

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

動(dòng)詞應(yīng)該使用現(xiàn)在時(shí)
- 不要將動(dòng)詞通過(guò)介詞轉(zhuǎn)為形容詞

代碼評(píng)論

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

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

代碼評(píng)論

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

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

代碼用處

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

代理方法

代理方法是對(duì)象能夠在其代理中喚醒調(diào)用當(dāng)某種事件發(fā)生的時(shí)候。它們有一種特殊的形式，這種形式同樣適用于一個(gè)對(duì)象數(shù)據(jù)源的方法中。
- 以表示發(fā)送消息的對(duì)象所屬類來(lái)命名開(kāi)頭

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

該類的名字省略了前綴并且以小寫字母開(kāi)頭。

• 冒號(hào)在類名后面（對(duì)于代理對(duì)象來(lái)說(shuō)參數(shù)是一個(gè)引用）除非方法只有一個(gè)參數(shù)，這個(gè)參數(shù)就是消息發(fā)送者。

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

• 有一種例外就是消息通知發(fā)送的消息。這種情況下，唯一的參數(shù)是通知對(duì)象。

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

• 代理方法使用“did”或者“will”通知代理已經(jīng)發(fā)生了或者將要發(fā)生什么？

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

• 盡管代理方法可以使用“did”或者“will”，我們推薦使用“should”。

- (BOOL)windowShouldClose:(id)sender;

集合方法

對(duì)于管理著一些對(duì)象（每一個(gè)對(duì)象稱為一個(gè)元素）的集合對(duì)象，對(duì)一些方法如下的約定。

- (void)addElement:(elementType)anObj;- (void)removeElement:(elementType)anObj;- (NSArray *)elements;

例子：

- (void)addLayoutManager:(NSLayoutManager *)obj;- (void)removeLayoutManager:(NSLayoutManager *)obj;- (NSArray *)layoutManagers;

下面是對(duì)這個(gè)指南的一些限制條件和改進(jìn)

• 如果集合是無(wú)序的，返回一個(gè)NSSet，不要返回一個(gè)NSArray
• 若需要將對(duì)象插入到集合的某個(gè)特定位置，使用類似于如下的方法

- (void)insertLayoutManager:(NSLayoutManager *)obj atIndex:(int)index; - (void)removeLayoutManagerAtIndex:(int)index;

需要記憶的一些集合方法的細(xì)節(jié)

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

對(duì)于上面的規(guī)范有一些自于NSWindow類的集合方法

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

方法參數(shù)

私有方法

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

函數(shù)命名

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

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

• 大部分函數(shù)以描述函數(shù)意義的動(dòng)詞開(kāi)頭

NSHighlightRectNSDeallocateObjec

查詢屬性的函數(shù)有更多的一些規(guī)則
- 如果函數(shù)返回其第一個(gè)參數(shù)的屬性，需要省略動(dòng)詞。

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

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

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

• 如果返回一個(gè)boolean值，應(yīng)該以一個(gè)變形的動(dòng)詞開(kāi)頭

BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)

屬性和數(shù)據(jù)類型命名

聲明屬性和實(shí)例變量

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

舉例

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

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

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

許多情況下，當(dāng)使用一個(gè)已經(jīng)聲明的屬性也應(yīng)該合成相應(yīng)的實(shí)例變量。
確保實(shí)例變量的名字簡(jiǎn)潔地描述存儲(chǔ)屬性。通常你不應(yīng)該直接訪問(wèn)實(shí)例變量。應(yīng)該通過(guò)訪問(wèn)方法來(lái)訪問(wèn)。為了有助于標(biāo)志實(shí)例變量，可以使用下劃線開(kāi)頭，例如：

@implementation MyClass {BOOL _showsTitle; }

如果使用一個(gè)已經(jīng)聲明的屬性來(lái)合成實(shí)例變量，在@synthesize語(yǔ)句中詳細(xì)說(shuō)明實(shí)例變量。

@implementation MyClass @synthesize showsTitle=_showsTitle;

一些注意事項(xiàng)
- 不要顯示的聲明一個(gè)公開(kāi)的實(shí)例變量
- 如果需要聲明一個(gè)實(shí)例變量，明確聲明是@private 或者@protected
- 如果一個(gè)實(shí)例變量一個(gè)可訪問(wèn)的實(shí)例屬性，確保為這個(gè)實(shí)例變量編寫了訪問(wèn)器方法

常量

常量根據(jù)創(chuàng)建方式的不同，規(guī)則也不一樣。

枚舉常量

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

使用const創(chuàng)建常量

使用const的例子

const float NSLightGray;

其他類型的常量

• 通常，不要使用#define預(yù)處理器命令來(lái)創(chuàng)建常量。
• 使用大寫，舉例

#ifdef DEBUG

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

__MACH__

通知和異常

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

通知

如果一個(gè)類有代理，那么代理會(huì)通過(guò)事先定義好的代理方法來(lái)接受大多數(shù)的通知。這些通知名稱應(yīng)該反映相應(yīng)的代理方法。例如,全局的NSApplication對(duì)象的自動(dòng)注冊(cè)的代理會(huì)接受applicationDidBecomeActive:的消息當(dāng)app發(fā)送一個(gè)NSApplicationDidBecomeActiveNotification的通知。

通知使用NSString來(lái)表示，使用下面的方式來(lái)命名：

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

例如:

NSApplicationDidBecomeActiveNotificationNSWindowDidMiniaturizeNotificationNSTextViewDidChangeSelectionNotificationNSColorPanelColorDidChangeNotification

異常

使用全局的NSString對(duì)象來(lái)表示異常，命名組成如下：

[Prefix] + [UniquePartOfName] + Exception

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

NSColorListIOExceptionNSColorListNotEditableExceptionNSDraggingExceptionNSFontUnavailableExceptionNSIllegalSelectorException

可接受的簡(jiǎn)寫和縮寫

通常，不應(yīng)該對(duì)接口的名稱進(jìn)行縮寫。然而，下面列出的縮寫已經(jīng)被創(chuàng)建或者在過(guò)去被使用了很久，因此，可以繼續(xù)使用。關(guān)于縮寫有一些其他需要注意的地方：
- 來(lái)源于標(biāo)準(zhǔn)C庫(kù)的一些縮寫，例如‘a(chǎn)lloc’和‘getc’是被允許的。
- 在參數(shù)的命名中可以更加自由的使用縮寫。

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.

在計(jì)算機(jī)產(chǎn)業(yè)中使用的縮寫和首字母縮略詞你可能使用到，下面有些熟知的縮略詞：

ASCII

PDF

XML

HTML

URL

RTF

HTTP

TIFF

JPG

PNG

GIF

LZW

ROM

RGB

CMYK

MIDI

FTP

對(duì)于框架開(kāi)發(fā)者的小技巧

這部分是關(guān)于框架開(kāi)發(fā)者的一些建議，略…

總結(jié)

以上是生活随笔為你收集整理的Cocoa编程指南的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。