General Principles

Clarity

• It is good to be both clear and brief as possible, but clarity shouldn’t suffer because of brevity:

  Code	Commentary
  insertObject:atIndex:	Good.
  insert:at:	Not clear; what is being inserted? what does “at” signify?
  removeObjectAtIndex:	Good.
  removeObject:	Good, because it removes object referred to in argument.
  remove:	Not clear; what is being removed?

• In general, don’t abbreviate names of things. Spell them out, even if they’re long:

  Code	Commentary
  destinationSelection	Good.
  destSel	Not clear.
  setBackgroundColor:	Good.
  setBkgdColor:	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
  sendPort	Does it send the port or return it?
  displayName	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
  - (NSInteger)tag	Defined in NSView, NSCell, NSControl.
  - (void)setStringValue:(NSString *)	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
  NSUnderlineByWordMask	Okay.
  NSTableViewColumnDidMoveNotification	Okay.

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

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

Typographic Conventions

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 (for example, runTheWordsTogether)—this is known as camel-casing. 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 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.

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.

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:

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

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.

  Header file	Declares
  NSLocale.h	The NSLocale 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.h	NSString and NSMutableString classes.
  NSLock.h	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
  Foundation.h	Foundation.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).