---

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.

Contents:

General Principles
Prefixes
Typographic Conventions
Class and Protocol Names
Header Files

General Principles

Clarity

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

  insertObject:atIndex:	good
  insert:at:	not clear; what is being inserted? what does “at” signify?
  removeObjectAtIndex:	good
  removeObject:	also 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:

  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.

  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.

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

  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.

  NSUnderlineByWordMask

  NSTableViewColumnDidMoveNotification

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 “subprefixes.” 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. 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.

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

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

---