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.
Clarity
It is good to be both clear and brief as possible, but clarity shouldn’t suffer because of brevity:
Code | Commentary |
---|---|
|
good |
|
not clear; what is being inserted? what does “at” signify? |
|
good |
|
also good, because it removes object referred to in argument |
|
not clear; what is being removed? |
In general, don’t abbreviate names of things. Spell them out, even if they’re long:
Code | Commentary |
---|---|
|
good |
|
not clear |
|
good |
|
not clear |
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.
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.
Code | Commentary |
---|---|
|
Does it send the port or return it? |
|
Does it display a name or return the receiver’s title in the user interface? |
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.
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.
Code | Commentary |
---|---|
|
Defined in NSView, NSCell, NSControl |
|
Defined in a number of Cocoa classes |
See also “Method Arguments.”
No Self Reference
Names shouldn’t be self-referential.
Code | Commentary |
---|---|
NSString |
okay |
NSStringObject |
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.
Code | Commentary |
---|---|
| okay |
| okay |
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).
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
Prefix |
Cocoa Framework |
---|---|
NS |
Foundation |
NS |
Application Kit |
AB |
Address Book |
IB |
Interface Builder |
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
Follow a few simple typographical conventions when naming API elements:
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. However, note the following qualifications:
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).
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, especially in methods. 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.
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 Kit frameworks are full of examples; a few are NSString, NSDate, NSScanner, NSApplication, NSButton, and NSEvent.
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:
NSLocking |
good |
NSLock |
poor (seems like a name for a class) |
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.
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.
Header file |
Declares |
---|---|
|
The NSApplication class |
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.
Header file |
Declares |
---|---|
|
NSString and NSMutableString classes |
|
NSLocking protocol and NSLock, NSConditionLock, and NSRecursiveLock classes |
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.
Header file |
Framework |
---|---|
|
|
Adding 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.
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).
Last updated: 2010-05-05