面前对象软件库的设计经常被忽略的一个方便是类,方法,函数,常量以及编程接口的其他元素的命名。本章节讨论Cocoa界面的大多数项目通用的几个命名约定。
一般原则
明晰
尽可能清晰简洁是很好的,但是清晰度不应该由于简洁而受损
一般来说,不要缩写名称。尽可能的拼出来,尽管它们可能很长
您可能认为缩写是中所周知的,但是可能不是这样,特别是遇到您的方法或函数名称的是具有不同的文化和语言背景的开发人员。
然而,一些缩略是真正常见的,具有悠久的使用历史。您可以继续使用它们;请参阅 Acceptable Abbreviations and Acronyms
** 避免API名称中的歧义,例如可以以多种方式解释的方法名称。**
一致性
** 尝试在整个Cocoa编程接口中使用名称。如果您不确定,请浏览当前头文件或参考文档以获取先例**
当你有一个类的方法需要利用多态时,一致性时特别重要的。在不同类中执行相同的操作方法,应该具有相同的名称
另请参见Method Arguments
非自我引用
名称不应该时自引用的
作为掩码(因此可以按位操作组合)的常量是此规则的一个例外,通知名称的常量也是例外。
前缀
前缀是编程接口中名称的重要组成部分。它们区分软件的功能区域。通常这个软件包装在一个框架中,或者在紧密相关的框架中(如基金会和应用程序包的情况)。前缀可防止第三方开发人员和Apple定义的符号之间的冲突(以及Apple自己的框架中的符号之间)。
前缀具有规定的格式。它由两个或三个大写字母组成,不使用下划线或“子前缀”。以下是一些示例
命名类,协议,函数,常量和typedef结构时使用前缀。千万不能命名方法时,使用前缀;方法存在于定义它们的类创建的命名空间中。另外,不要使用前缀来命名结构的字段。
排版约束
命名API元素时,请遵循一些简单的排版约定:
- 对于由多个单词组成的名称,请勿使用标点符号作为名称或分隔符非一部分(下划线、破折号等);相反,大写每个单词的第一个字母,并把这些单词组合到一起(例如runTheWordsTogether) - 这被称为驼峰命名法。但是,请注意以下资格:
- 对于方法名称,请从小写字母开始,并将单词的第一个字母大写。不要使用前缀。
fileExistsAtPath:isDirectory:
这个指南的一个例外是以一个著名的首字母缩写开头的方法名称,例如TIFFRepresentation(NSImage)。
- 对于函数和常量的名称,使用与相关类相同的前缀,并将嵌入字的第一个字母大写。
NSRunAlertPanel
NSCellDisabled
- 避免使用下划线字符作为方法名称中的私有的前缀(允许使用下划线字符作为实例变量名称的前缀)。苹果保留这个使用这个惯例。第三方的使用可能导致命名空间的冲突;他们可能会无意中用自己的一种方法覆盖现有的私有方法,造成灾难性的后果。有关私有API遵循的约定的建议,请参阅私有方法
类和协议名称
一个类的名字应该明确指出类(或类的对象)代表或做什么的名词。该名称应该有一个适当的前缀。基础和应用框架充满了实例;例如:NSString,NSDate,NSScanner,NSApplication,UIApplication,NSButton,和UIButton。
协议应根据他们的行为组合来命名:
- 大多数协议组相关的方法,与任何类都没有关联。这种类型的协议应该以不与一个类混淆的方式命名。一种常用的做法是使用动名词形式("...ing")例如:
- 一些协议组合了一些不相关的方法(而不是创建几个单独的小协议)。这些协议通常与作为协议主要表达式的类相关联。在这些情况下,约定是给协议与类相同的名称。
这种协议的一个例子是NSobject协议。此协议的分组的方法可以用于查询其在类层次结构中的位置的任何对象,以使其调用特定方法,并增加或减少其引用计数。因为NSObject类提供了这些方法的主要表达式,所以协议以类命名。
头文件
如何命名头文件很重要,因为您使用的约定表示文件包含了什么:
- 声明一个孤立的类或协议。如果类或协议不是组的一部分,请将其声明放在单独的文件中,其名称是声明的类或协议的文件。
- 声明相关的类和协议。对于一组相关的声明(类,类和协议),将声明放在一个包含主类,类别或协议的名称的文件中。
- 包含框架头文件。每个框架应该有一个头文件,以框架命名,包括框架的所有公开头文件。
- 将API添加到另一个额框架中的类中。如果您在一个框架中声明在另一个框架的类的类别中的方法,则将“Additions”附加到原始类的名称; 一个例子是 Application Kit 的头文件NSBundleAdditions.h 。
- 相关功能和数据类型。如果您有一组相关函数,常量,结构和其他类型数据,请将它们放在适当命名的头文件中。(例如:Application Kit 的NSGraphics.h)。