Cocoa 编码指南 代码命名基础

本节主题包括Cocoa命名约定以及我们提倡的框架编程实践。使用公共API开发Cocoa框架、插件及其他可执行文件需要使用的方法和约定不同于应用程序开发。如果产品主要客户是开发人员，则保证产品的编程接口清晰明确，不至于让开发者产生疑惑十分重要。

这种情况下，API命名约定就可以派上用场，它可以帮助您保持编程接口一致明确。另外，框架开发领域也存在一些特定的编程技术—或者说，这些技术对框架开发更加重要—例如版本管理，二进制兼容性，错误处理以及内存管理等。

在面向对象软件库的设计过程中，开发人员经常忽视对类、方法、函数、常量以及其他编程接元素的命名。本节讨论大多数Cocoa接口通用的几条命名约定。

一般性原则清晰

最好是既清晰又尽可能地简短，但不要为了追求简短而丧失清晰性：

insertObject:atIndex:好的命名  


insert:at:不清晰；插入什么？“at”表示什么？   


removeObjectAtIndex:好的命名  


removeObject:这样命名也不错，因为方法将移除通过参数引用的对象。  


remove:不清晰：要移除什么？ 

通常情况下，请不要缩写事物的名称，即使名称很长，也应该把它完全拼写出来。

destinationSelection：好的命名  


destSel：不清晰  


setBackgroundColor:好的命名  


setBkgdColor:不清晰 

您可能觉得某个缩写众所周知，但实际可能并非如此。特别是具有不同文化和语言背景的开发人员，在遇到您提供的方法或函数的名称缩写时，他们可能不明白其中的含义。

不过，有一些缩写确实很常见并且有很长的使用历史。因此，您可以继续使用。请参看“可以接受的缩略名称”一节以了解更多的信息。

要防止API的名称出现歧义。这里的歧义是指名称具有多种解释方式。

sendPort:该方法是把端口发送出去还是返回发送端口呢？
 
displayName:该方法是显示某个名称还是返回用户界面中接收者的标题呢？
 
一致性

请尽可能在Cocoa编程接口中保持名称一致性。如果不太有把握做到这一点，则请浏览一下头文件和参考文档中的范例。

如果类方法利用多态，一致性就显得尤其重要。因为在这种情况下，不同类用于完成同样事件的方法必须具有相同的名称。

(int)tag:该方法同时定义在 NSView、 NSCell、 NSControl这三个类里面。  


(void)setStringValue:(NSString *):该方法定义于数个Cocoa类中 

您可以参看 “方法参数”一节。

不能自我指涉

名称不应该自我指涉。

NSString:可以使用
 
NSStringObject:该名称自我指涉

掩码的常量（可以使用位操作进行组合）不适用这条规则，作为通告的常量也不适用。

NSUnderlineByWordMask  


NSTableViewColumnDidMoveNotification 

前缀

前缀是编程接口名称的重要部分，它们可以区分软件的功能范畴。通常情况下，提供编程接口的软件会被打包成框架（Foundation框架以及 Application Kit框架就是如此）或者是和框架紧密相关的产品，我们可以利用前缀来区分框架的功能范畴。另外，前缀可以防止第三方开发者定义的符号和苹果公司定义的符号发生冲突（以及防止苹果公司不同框架之间的符号发生冲突）。

前缀有规定的格式。它需要由两个或者三个大写字符组成，而且不能使用下划线或者“子前缀”。下面是一些例子：

前缀Cocoa的框架  


NS Foundation框架  


NS Application Kit框架  


AB Address Book框架  


IB Interface Builder框架 

在为类，协议，函数，常量以及通过typedef定义的结构命名时，请使用前缀。但在命名方法时，请不要使用前缀，因为方法已经存在于其定义类所创建的名称空间中。同理，在定义结构的字段时，也不要使用前缀。

书写约定

为API元素命名的时候， 请遵循下面这几条简单的书写约定：

对于含有多个单词的名称，请不要使用标点符号标志和分割符（下划线，破折号之类）；而是要大写每个单词的首字符并且把这些单词连续地拼写在一起。然而如下这些限定条件您也需要注意：

方法的名称要以一个小写字符开头，而名称中单词的首字符应该大写。另外，请不要在方法的名称中使用前缀。

fileExistsAtPath:isDirectory:  

如果方法名称的开头是某个众所周知的缩略语，则该原则就不适用。例如TIFFRepresentation (NSImage)，该名称就不遵循该原则。

函数或常量名称使用其关联类的前缀，并且要名称中单词的首字符要大写。

NSRunAlertPanel   


NSCellDisabled  

请不要使用下划线作为前缀来表示私有的属性，尤其是不要在类方法中使用。因为苹果公司保留使用这种方式，如果第三方再使用，就有可能会导致名称空间冲突。他们有可能在无意中用自己的方法覆盖了一个已经存在的私有方法，这样做将会带来灾难性的后果。请参看“私有方法”一节。您可以了解到我们提倡的可供私有API使用的约定。

类和协议的名称

类的名称应包含一个名词，这个名词明确地指示这个类(或者类对象)表示什么或者要做什么。此外，类名称还应该包含适当的前缀。（请参考“前缀”一节）。Foundation框架以及Application Kit框架就有很多这样的例子，例如NSString， NSDate，NSScanner，NSApplication，NSButton， 以及NSEvent。

我们应根据协议对方法的分组方式来为其命名：

大部分协议会把一些彼此相关但又不合类关联的方法归结在一起，形成一个特殊的方法集合。这种协议要合理地命名，不要将其和类名混淆。一种常见的约定是使用动名词格式（“...ing”）:

NSLocking:好  


NSLock:差（看起来像是个类名） 

有一些协议会把一些彼此无关的方法归结在一起（不是创建几个独立的小协议）。对于这样的协议，我们倾向于把它和一个类联系起来，利用类来作为协议的主要表现。并且，我们约定让此种协议使用和类一样的名称。

NSObject协议就是这种情况。它把一些不相关的方法组合在一起，这些方法有的用于查询任何对象在类层次中的位置，有的可以调用对象的特定方法，有的可以用来增加或者减少对象的引用计数。由于NSObject类提供了这些方法的主要表现，所以我们使用类名作为协议名称。

头文件

头文件的命名方式很重要，因为通过使用合理的命名约定，您利用文件名称来指示文件中包含的内容：

声明一个独立的类或协议。.如果一个类或协议不属于某个群，则请将其声明放置在一份独立的文件，并使用其名称作为文件名。

头文件：NSApplication.h  


声明：NSApplication类  

声明相关联的类或者协议：如果一群声明（类，类别以及协议）彼此相关，则请将它们放在一份文件，并使用主要的类或者协议名称作为文件名。

头文件：NSString.h  


声明：NSString 和 NSMutableString这两个类  

头文件：NSLock.h  


声明：NSLocking协议以及 NSLock， NSConditionLock，和 NSRecursiveLock这几个类 

包含框架头文件。每个框架都应该包含一份头文件，它的名称和框架名相同，而内容则包含了框架的全部公共头文件。

头文件：Foundation.h  


框架：Foundation框架 

为另一个框架里的某个类添加API。如果您在一个框架中声明一些方法，而这些方法属于另一个框架中某个类的范畴类，则请在原始类的名称后加上“Additions”，然后将其作为头文件的名称。例如Application Kit框架中的NSBundleAdditions.h头文件就是这种处理方式。

相关联的函数和数据类型。如果一群函数，常量，结构以及其他数据类型彼此相互关联，则请将它们放入到合理命名的头文件，例如NSGaphics.h(位于Application Kit)。