Naming Instance Variables and Data Types

This section describes the naming conventions for instance variables, constants, exceptions, and notifications.

Instance Variables

There are a few considerations to keep in mind when adding instance variables to a class:

• Avoid creating public instance variables. Developers should concern themselves with an object’s interface, not with the details of how it stores its data.

• Explicitly declare instance variables either @private or @protected. If you expect that your class will be subclassed, and that these subclasses will require direct access to the data, use the @protected directive.

• Make sure the name of the instance variable concisely describes the attribute stored.

If an instance variable is to be an accessible attribute of objects of the class, make sure you write accessor methods for it.

Constants

The rules for constants vary according to how the constant is created.

Enumerated constants

• Use enumerations for groups of related constants that have integer values.

• Enumerated constants and the typedef under which they are grouped follow the naming conventions for functions (see “Naming Functions”). The following example comes from NSMatrix.h :

  typedef enum _NSMatrixMode {

  NSRadioModeMatrix = 0,

  NSHighlightModeMatrix = 1,

  NSListModeMatrix = 2,

  NSTrackModeMatrix = 3

  } NSMatrixMode;

  Note that the typedef tag (_NSMatrixMode in the above example) is unnecessary.

• You can create unnamed enumerations for things like bit masks, for example:

  enum {

  NSBorderlessWindowMask = 0,

  NSTitledWindowMask = 1 << 0,

  NSClosableWindowMask = 1 << 1,

  NSMiniaturizableWindowMask = 1 << 2,

  NSResizableWindowMask = 1 << 3

  };

Constants created with const

• Use const to create constants for floating point values. You can use const to create an integer constant if the constant is unrelated to other constants; otherwise, use enumeration.

• The format for const constants is exemplified by the following declaration:

  const float NSLightGray;

  As with enumerated constants, the naming conventions are the same as for functions (see “Naming Functions”).

Other types of constants

• In general, don’t use the #define preprocessor command to create constants. For integer constants, use enumerations, and for floating point constants use the const qualifier, as described above.

• Use uppercase letters for symbols that the preprocessor evaluates in determining whether a block of code will be processed. For example:

  #ifdef DEBUG

• Note that macros defined by the compiler have leading and trailing double underscore characters. For example:

  __MACH__

• Define constants for strings used for such purposes as notification names and dictionary keys. By using string constants, you are ensuring that the compiler verifies the proper value is specified (that is, it performs spell checking). The Cocoa frameworks provide many examples of string constants, such as:

  APPKIT_EXTERN NSString *NSPrintCopies;

  The actual NSString value is assigned to the constant in an implementation file. (Note that the APPKIT_EXTERN macro evaluates to extern for Objective-C.).

Exceptions and Notifications

The names for exceptions and notifications follow similar rules. But both have their own recommended usage patterns.

Exceptions

Although you are free to use exceptions (that is, the mechanisms offered by the NSException class and related functions) for any purpose you choose, Cocoa has traditionally not used them to handle regular, expected error conditions. For these cases, use returned values such as nil, NULL, NO, or error codes. It typically reserves exceptions for programming errors such an array index being out of bounds.

Exceptions are identified by global NSString objects whose names are composed in this way:

[Prefix] + [UniquePartOfName] + Exception

The unique part of the name should run constituent words together and capitalize the first letter of each word. Here are some examples:

NSColorListIOException

NSColorListNotEditableException

NSDraggingException

NSFontUnavailableException

NSIllegalSelectorException

Notifications

If a class has a delegate, most of its notifications will probably be received by the delegate through a defined delegate method. The names of these notifications should reflect the corresponding delegate method. For example, a delegate of the global NSApplication object is automatically registered to receive an applicationDidBecomeActive: message whenever the application posts an NSApplicationDidBecomeActiveNotification.

Notifications are identified by global NSString objects whose names are composed in this way:

[Name of associated class] + [Did | Will] + [UniquePartOfName] + Notification

For example:

NSApplicationDidBecomeActiveNotification

NSWindowDidMiniaturizeNotification

NSTextViewDidChangeSelectionNotification

NSColorPanelColorDidChangeNotification