Code Naming Basics

基础的代码命名

An often overlooked aspect of the design of object-oriented software libraries is the naming of classes, methods, functions, constants, and the other elements of a programmatic interface. This section discusses several of the naming conventions common to most items of a Cocoa interface.
对于面向对象软件库的设计，经常忽视的一点是类、方法、函数、常量以及其它编程接口元素的命名。本部分将会讨论对于大多数的Cocoa接口的一些通用的命名约定。

General Principles

总则

Clarity
简洁

• It is good to be both clear and brief as possible, but clarity shouldn’t suffer because of brevity:
• 尽可能的简单、明了，但是过于简单，会偏离明了：

• In general, don’t abbreviate names of things. Spell them out, even if they’re long:
• 一般来说，不要缩略事物的名字。使用全拼，即使单词比较长：

You may think an abbreviation is well-known, but it might not be, especially if the developer encountering your method or function name has a different cultural and linguistic background.
你可以能认为有些缩写比较有名，其实非你所料，尤其是当你的方法或者函数名遇到一个不同文化和语言的开发者。

译者注：ifeegoo，比如在中国，很多人IT行业人员都知道BAT表示Baidu，Alibaba，Tencent，但是歪果仁不一定知道滴。其实一个缩写词，在不同的语言环境，很有可能表示几十甚至上百种意思，有一个专门查询缩写词网站：http://www.abbreviations.com/。我之前在做Android开发的时候，很喜欢用全拼，这样能够描述的很清楚，也不会让人产生歧义。那又有人说，既然这么推荐全拼，为什么C语言采用这种printf的命名呢？这是一个好的问题。这个在很大一个程度上是因为之前没有强大的IDE，只能靠程序员自己记忆方法名，如果说你记不完全的话，这个代码岂不是无法向下进行呢？

• However, a handful of abbreviations are truly common and have a long history of use. You can continue to use them; see Acceptable Abbreviations and Acronyms.

• 然而，少数缩写词确实常见，而且有很长的使用历史。你可以继续使用它们；可以参见可接受的缩略词和首字母缩略词。

• Avoid ambiguity in API names, such as method names that could be interpreted in more than one way.

• 避免模棱两可的API命名，例如具有多种解释的方法名。

Consistency
一致性

• Try to use names consistently throughout the Cocoa programmatic interfaces. If you are unsure, browse the current header files or reference documentation for precedents.

• 在整个Cocoa编程接口中的命名保持一致性。如果你不太确定，请查看当前的头文件或者引用文档。

• Consistency is especially important when you have a class whose methods should take advantage of polymorphism. Methods that do the same thing in different classes should have the same name.

• 当你一个类的方法需要利用到多态，这种情况下一致显得尤为重要。方法需要在不同的类中具有相同的作用，并且需要有相同的名字。

See also Method Arguments.
参见方法参数。

No Self Reference
无自引用

译者注：ifeegoo 无自引用的意思应该是指不能在当前命名中附带本身的属性，比如一个人叫张三，我们不要把他叫做张三人、人张三。

• Names shouldn’t be self-referential.
• 名字不能自引用。

• Constants that are masks (and thus can be combined in bitwise operations) are an exception to this rule, as are constants for notification names.
• TODO

Prefixes

前缀

Prefixes are an important part of names in programmatic interfaces. They differentiate functional areas of software. Usually this software comes packaged in a framework or (as is the case of Foundation and Application Kit) in closely related frameworks. Prefixes protect against collisions between symbols defined by third-party developers and those defined by Apple (as well as between symbols in Apple’s own frameworks).
在编程接口命名中，前缀是一个重要部分。这个是用来区分软件不同的功能范围。这样的不同的范围，通常是一个框架中的包或者（例如基础框架和应用包）相关的框架。前缀能够防止第三方开发者定义的内容与Apple定义的内容相冲突。

• A prefix has a prescribed format. It consists of two or three uppercase letters and does not use underscores or “sub prefixes.” Here are some examples:
• 前缀有规定的格式。它包含2-3个大写字母，并且不会使用下划线分割或者“子前缀”。下面有些例子：

• Use prefixes when naming classes, protocols, functions, constants, and typedef structures. Do not use prefixes when naming methods; methods exist in a name space created by the class that defines them. Also, don’t use prefixes for naming the fields of a structure.
• 在类、协议、函数、常量和定义结构体命名的时候，请使用前缀。不要在方法命名的时候使用前缀；方法是有通过类来定义的命名空间。同样，不要在结构体内的字段上使用前缀。

Typographic Conventions

排版约定

Follow a few simple typographical conventions when naming API elements:
在API元素命名的时候，请遵循一些简单的排版约定：

• For names composed of multiple words, do not use punctuation marks as parts of names or as separators (underscores, dashes, and so on); instead, capitalize the first letter of each word and run the words together (for example, runTheWordsTogether)—this is known as camel-casing. However, note the following qualifications:
• 对于由多个单词组成的命名，不要使用标点符号作为名字的一部分，或者作为分隔符（下划线、破折号等）；而且每个单词的首字母要大写，并且连在一起(例如，runTheWordsTogether)-这个被称为驼峰式命名法。然而，要注意以下限制：

For method names, start with a lowercase letter and capitalize the first letter of embedded words. Don’t use prefixes.
对于方法的命名，请一小写字母大头，紧接着后面一个单词的首字母大写。不要使用前缀。

fileExistsAtPath:isDirectory:

An exception to this guideline is method names that start with a well-known acronym, for example, TIFFRepresentation (NSImage).
对于方法的命名有一个例外的地方就是以一个有名的首字母缩写词打头，例如NSImage的TIFFRepresentation方法。

For names of functions and constants, use the same prefix as for related classes and capitalize the first letter of embedded words.
对于函数和常量的命名，对于相关的类使用相同的前缀，并且紧接着后面的一个单词首字母大写。

NSRunAlertPanel
NSCellDisabled

• Avoid the use of the underscore character as a prefix meaning private in method names (using an underscore character as a prefix for an instance variable name is allowed). Apple reserves the use of this convention. Use by third parties could result in name-space collisions; they might unwittingly override an existing private method with one of their own, with disastrous consequences. See Private Methods for suggestions on conventions to follow for private API.
• 避免使用下划线字符作为私有方法的命名前缀（对于使用下划线字符作为实例变量的命名前缀是允许的）。Apple保留这种约定的使用权。如果第三方使用，可能会导致命名空间的冲突；可能会在毫不知情的情况下覆盖了其中一个已经存在的私有方法，从而带来灾难性的后果。参见私有方法部分来获取对于私有API方法命名的约定建议。

Class and Protocol Names

类和协议的命名

The name of a class should contain a noun that clearly indicates what the class (or objects of the class) represent or do. The name should have an appropriate prefix (see Prefixes). The Foundation and application frameworks are full of examples; a few are NSString, NSDate, NSScanner, NSApplication, UIApplication, NSButton, and UIButton.
类的命名中应当包含一个能够清楚的表明这个类（或者类的对象）是什么，或者是做什么的名词。这个名字需要有一个适当的前缀。Foundation框架和应用框架里面到处都是例子；例如： NSString, NSDate, NSScanner, NSApplication, UIApplication, NSButton, and UIButton。

Protocols should be named according to how they group behaviors:
协议应该依据组作用来命名：

• Most protocols group related methods that aren’t associated with any class in particular. This type of protocol should be named so that the protocol won’t be confused with a class. A common convention is to use a gerund (“…ing”) form:
• 一般情况下，大多数协议组相关的方法与任何类都不相关。这种类型的协议应该在命名上与类区分开来。一个常见的约定就是使用动名词（“…ing”）格式：

• Some protocols group a number of unrelated methods (rather than create several separate small protocols). These protocols tend to be associated with a class that is the principal expression of the protocol. In these cases, the convention is to give the protocol the same name as the class.
• 一些协议中包含多个不相关的方法(而不是创建多个单独的小的协议)。这些协议与类相关，这是协议最重要的表达方式。在这种情况下，我们约定，保持协议和类名相同的方式。

An example of this sort of protocol is the NSObject protocol. This protocol groups methods that you can use to query any object about its position in the class hierarchy, to make it invoke specific methods, and to increment or decrement its reference count. Because the NSObject class provides the primary expression of these methods, the protocol is named after the class.
这种协议的例子就是NSObject协议。可以使用这个协议中的方法来查询任意类层级的对象的位置，可以调用指定方法，增加或减少它的引用数。因为类NSObject提供了这些方法的初始表达式，协议的命名在类名之后。

Header Files

头文件

How you name header files is important because the convention you use indicates what the file contains:
你如何命名头文件非常重要，因为约定中，你用它来显示这个文件包含的内容：

• Declaring an isolated class or protocol. If a class or protocol isn’t part of a group, put its declaration in a separate file whose name is that of the declared class or protocol.
• 声明一个单独的类或协议。如果一个类或协议不属于一个组的一部分，将它的声明放在一个单独的文件中，这个文件的名字是已经声明过的类或者协议。

• Declaring related classes and protocols. For a group of related declarations (classes, categories, and protocols), put the declarations in a file that bears the name of the primary class, category, or protocol.
• 声明相关的类和协议。对于一个含有相关声明的组（类、分类和协议），将声明放在一个与初始类、分类或协议命名相关的文件中。

• Including framework header files. Each framework should have a header file, named after the framework, that includes all the public header files of the framework.
• 包含框架头文件。每一个框架应当有一个头文件，在框架后面命名，这个头文件应当包含所有的框架的公共头文件。

• dding API to a class in another framework. If you declare methods in one framework that are in a category on a class in another framework, append “Additions” to the name of the original class; an example is the NSBundleAdditions.h header file of the Application Kit.

• 在其它框架中添加API到一个类中。如果你想要在一个框架中中声明一个在其它框架中类的分类中的方法，请在原始类的命名后面追加“Additions”；一个典型的例子就是应用包中的NSBundleAdditions.h 头文件。

• Related functions and data types. If you have a group of related functions, constants, structures, and other data types, put them in an appropriately named header file such as NSGraphics.h (Application Kit).

• 相关的函数和数据类型。如果你有一组相关的函数、常量、结构体以及其它数据类型，可以将他们放在一个恰当命名的头文件中，例如 NSGraphics.h（应用包）。