Cocoa 编码指南 为方法命名

Cocoa 编码指南 为方法命名是本文要介绍的内容，方法可能是编程接口中最常见的元素了，因此对其命名要特别注意。本部分讨论方法命名的相关方面：

通用规则

为方法命名时，请记住下面这些通用的指导原则：

方法名称应以小写字符开头，名称中的单词首字符要大写。另外，请不要在方法名称中使用前缀。您可以参考“书写约定”一节，以了解更多信息。

有两种特定的情况不适用该原则。其一，方法的名称可以使用某个众所周知的缩写开头，而该缩写可以大写（例如，TIFF 或者PDF）。其二，您可以使用前缀来分组并区分私有方法（请参考“私有方法”一节）。

如果方法代表一个对象执行的动作，则其名称应该以一个动词开头：

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

请不要使用 “do”或者 “does”作为名称的一部分，因为这些辅助性的动词 不能为名称增加更多的含义。同时，请不要在动词之前使用副词或者形容词。

如果方法返回接收者的某个属性，则以属性名称作为方法名。如果方法没有间接地返回一个或多个值，您也无须使用”get“这样的单词。

(NSSize)cellSize;正确  
(NSSize)calcCellSize;错误  
(NSSize)getCellSize; 错误 

您可以参考 “存取方法”一节，以了解更多的信息。

所有参数前面都应使用关键字。

(void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag;正确  
(void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;错误 

参数前面的单词应能够对参数进行描述。

(id)viewWithTag:(int)aTag;正确  
(id)taggedView:(int)aTag;错误 

如果您当前创建的方法比起它所继承的方法更有针对性，则您应该在已有的方法名称后面添加关键字，并将其作为新方法的名称。

(id)initWithFrame:(NSRect)frameRect; NSView  
(id)initWithFrame:(NSRect)frameRect mode:(int)aMode cellClass:(Class)factoryId numberOfRows:(int)rowsHigh numberOfColumns:
(int)colsWide;NSMatrix是NSView的子类。 

请不要使用”and“来连接两个表示接受者属性的关键字。

(int)runModalForDirectory:(NSString *)path file:(NSString *) name types:(NSArray *)fileTypes;正确  
(int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes;错误 

虽然上面的例子使用”and“这个词感觉还不错，但是随着创建的方法所带有的关键字越来越多，这种方式会引起问题。

如果方法描述了两个独立的动作，请使用”and“把它们连接起来。

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

存取方法

存取方法用于设置或返回对象的属性（也就是对象的实例变量）。由于属性的表示方法不同，我们提倡的存取方法的格式也有差异：

如果某个属性使用名词来表示，则方法的格式如下：

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

例如：

(void)setColor:(NSColor *)aColor;   
(NSColor *)color;  

如果某个属性使用形容词表示， 则方法的格式为：

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

例如：

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

如果某个属性使用动词表示，则方法的格式为：

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

例如：

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

这种情况下，动词应使用一般现在时的格式。

请不要使用分词形式把动词转换为形容词：

(void)setAcceptsGlyphInfo:(BOOL)flag;正确  
(BOOL)acceptsGlyphInfo;正确  
(void)setGlyphInfoAccepted:(BOOL)flag;错误  
(BOOL)glyphInfoAccepted;错误 

您可以使用情态动词（在动词前冠以“can”,"should","will"等），使得方法的名称更加明确，但是请不要使用“do”或“does”这样的情态动词。

(void)setCanHide:(BOOL)flag;正确  
(BOOL)canHide;正确  
(void)setShouldCloseDocument:(BOOL)flag;正确  
(BOOL)shouldCloseDocument;正确  
(void)setDoesAcceptGlyphInfo:(BOOL)flag;错误  
(BOOL)doesAcceptGlyphInfo;错误 

只有当方法间接地返回对象或者数值，您才需要在方法名称中使用get"。这种格式只适用于需要返回多个数据项的方法。

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

如果方法格式和上面一样，则其实现应该能够接受NULL 参数，这样调用者才能够表明他们对其中的一个或者多个返回值不感兴趣。

委托方法

委托方法是指当某些事件发生时，对象在委托里调用的处理方法（如果委托实现了它们）。委托方法的格式独特，但它也适用于在对象数据源里调用的方法：

方法名称的开头应标识出发送消息的对象所属的类：

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

使用集合方法时， 您需要记住下面这两条实现细节：

上述方法通常隐含了它们对于被插入对象的所有权，因此，用于添加或者插入对象的代码必须增加对象的计数，而用于移除对象的代码也必须要释放对象。

如果被插入的对象需要有一个指针指向其幕后的主对象， 则通常情况下， 您应该使用 set...这样方法，它可以设置对象的背后对象指针，但并不增加其引用计数。我们以 insertLayoutManager:atIndex:方法为例，NSLayoutManager使用如下方法来实现这一功能：

(void)setTextStorage:(NSTextStorage *)textStorage;   
(NSTextStorage *)textStorage;  

正常情况下， 您应该不会直接调用setTextStorage:方法，但可能需要对其进行重写。

我们还有另外一个示列用于展示集合方法的上述约定，它来自于NSWindow类：

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

方法的参数

下面是数条和方法参数命名相关的通用规则：

和方法名称一样， 参数的名称也是以小写的字符开头，并且后续单词的首字符要大写。例如：removeObject:(id)anObject）。

请不要在参数名称中使用"pointer"或者"ptr"。您应该使用参数的类型来声明参数是否是一个指针。

请不要使用一到两个字符的名称作为参数名。

请不要使用只剩几个字符的缩写。

习惯上(在Cocoa中),我们把下面的关键字和参数应该组合在一起使用：

...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  

私有方法

大多数情况下，私有方法遵循和公共方法一样的命名规则。但是，有一种常见的约定是为私有方法添加一个前缀，这样我们就很容易区分它们。但即便是利用这样的约定，私有方法的名称还是有可能导致奇怪的问题。当您为某个Cocoa框架类设计子类时，您无法知道您的某个私有方法是否在无意中覆盖了具有相同名称的私有的框架方法。

大部分Cocoa框架中私有方法的名称都带有一个下划线前缀（例如，_fooData ），这个前缀把方法标记为私有。根据这样的实际情况，我们给出两条建议：

请不要在您的私有方法中使用下划线作为前缀，因为苹果公司保留使用这种命名约定。

在为某个很大的Cocoa框架类（例如NSView）派生子类时，如果需要绝对保证子类私有方法名称不会和超类发生冲突，则您可以为子类私有方法添加自己的前缀。前缀应该尽可能地具有***性，也许您的前缀可以基于公司或者项目名称，并且使用"XX_"这样的格式。例如，如果您的项目叫做Byte Flogger，则前缀可以是BF_addObject：这样的格式。

尽管为私有方法名称添加前缀似乎和早前我们对类方法的命名要求相矛盾，但这是因为此处的目的和早前不同：我们这么做是为了避免在无意中重写了超类中的私有方法。

小结：关于Cocoa 编码指南 为方法命名的内容介绍完了，希望本文对你有所帮助！推荐几篇相关内容：

Cocoa 编码指南 代码命名基础: http://mobile.51cto.com/iphone-274085.htm
Cocoa 编码指南 为函数命名: http://www.51cto.com/php/viewart.php?artID=274108  
Cocoa 编码指南 为方法命名: http://www.51cto.com/php/viewart.php?artID=274104
Cocoa 编码指南 为实例变量和数据类型命名:http://www.51cto.com/php/viewart.php?artID=274094
Cocoa 编码指南 框架开发者使用技巧和技术http://www.51cto.com/php/viewart.php?artID=274094