This is basically my notes of the documentation for Apple’s Coding Guidelines for Cocoa. To remember anything of the coding conventions I needed to write stuff down for myself and as such I’ve decided to make a blog post from it, almost purely for my own personal reference. I have also included some of the guidelines from tips and techniques for framework developers.

Cocoa Coding Conventions

  • Methods that return objects typically return nil if they cannot create or find the object.
  • Methods that perform an operation return a Boolean value to indicate success or failure.
  • If a method takes a collection object (NSArray, NSDictionary, NSSet) as an argument do not pass nil in place for an empty collection. Pass in an empty collection.
  • Use verbs in name of methods or functions that represent actions.

Introduction to Coding guidelines for Cocoa

Code Naming Basics

Clarity

  • Be clear but be as brief as possible. Clarity takes precedence.
  • Don’t abbreviate, spell them out even if they are long.
  • Avoid ambiguity.

Consistency

  • Use names consistently
  • Methods that do the same thing in different classes should have the same name.

Don’t be self referential. (NSString not NSStringObject). Exceptions are bit masks and notification names.

Use prefixes

  • To differentiate functional areas of software
  • Protect against collisions between symbol names.
  • Use prefixes when naming classes, protocols, functions, constants, and typedef structure.
  • Do not use prefixes when naming methods and don’t use prefixes for naming fields of a structure.

Typographic conventions

  • Do not use the underscore character as a prefix to indicate a private method.
  • You can use a underscore as a prefix for an instance variable.
  • Use camel case for method and function names
    • For method names, the first character of the method is lower case.
    • For function names, the first character of the function is upper case.
    • For functions & constants that belong to a particular API prefix their name with same prefix used in related classes.

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 and should be preceded by the appropriate prefix. NSDate, NSString, NSScanner etc.

Protocols should be named according to the behaviours they group and should be preceded by the appropriate prefix. A protocol and a class can have the same name. If they do they should be closely tied together.

  • 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. (See NSObject).

Header Files
For declaring an isolated class or protocol put its declaration in a separate file whose name is that of the declared class or protocol.

  • The NSLocale class is defined in NSLocale.h

For a group of related classes and protocols put the declarations in a file that bears the name of the primary class, category or protocol.

  • NSString and NSMutableString are contained in the NSString.h header file.
  • NSLocking protocol, NSLock, NSConditionLock, and NSRecursiveLock classes are contained in NSLock.h.

Each framework should have a header file, named after the framework that includes all the public header files of the framework.

If you create a category on a class append Additions to the name of the original class. For example NSBundleAdditions.h which contains a category of the NSBundle class.

If you have a group of related functions, constants and structures put them in a appropriately named header file.

Naming Methods
For methods that represent actions an object takes, start the name with a verb:

-(void)invokeWithTarget:(id)target;
-(void)selectTabeViewItem:(NSTabViewItem *)tabViewItem;

Do not use do, or does as part of the name.

If a method returns an attribute of the receiver, name the method after the  attribute. Do not use get unless arguments return values indirectly. Similar to accessor methods.

-(NSSize)cellSize; (correct)
-(NSSize)calcCellSize; (wrong)
-(NSSize)getCellSize; (wrong).

Use keywords before all arguments.

-(void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag; (correct)
-(void)sendAction:(SEL)aSelector : (id)anObject : (BOOL)flag; (wrong)

Make the word before the argument describe the argument.

- (id)viewWithTag:(int)aTag; (correct)
- (id)taggedView:(int)aTag; (wrong)

Don’t use “and” to link keywords that are attributes of the receiver.

- (int)runModalForDirectory:(NSString *)path file:(NSString *) name types:(NSArray *)fileTypes; (correct)
- (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes; (wrong)

If a method describes two separate actions, use “and” to link them.

-(BOOL)openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag; (correct)

Accessor Methods

Accessor methods are methods that are getters and setters for a value of a property of an object. They have certain recommended forms.

If a property is expressed as a noun the format is:

-(type)noun;
-(void)setNoun:(type)aNoun;

For example:

-(NSString *)title;
-(void)setTile:(NSString *)aTitle;

If the property is expressed as an adjective, property is often of type BOOL.

(BOOL)isEditable;
(void)setEditable:(BOOL)editableFlag;

If the property is expressed as a verb, the format is:

-(BOOL)showsAlpha;
-(void)setShowsAlpha:(BOOL)alphaFlag;

The verb should be in the simple present tense. Don’t force a verb into adjective form:

(void)setAcceptsGlyphInfo:(BOOL)acceptGlyphFlag; (correct)
(BOOL)acceptsGlyphInfo; (correct) (correct)
(void)setGlyphInfoAccepted:(BOOL) acceptGlyphFlag; (wrong)
(BOOL)glyphInfoAccepted; (wrong)

You can use modal verbs (can, should, will & so on) to clarify meaning but don’t use do or does.

-(void)setCanHide:(BOOL)canHideFlag; (correct)
-(BOOL)canHide; (correct)
-(void)setDoesAcceptGlyphInfo:(BOOL)glyphInfoFlag; (wrong)
-(BOOL)doesAcceptGlyphInfo; (wrong)

Use “get” only for methods that return object objects & values indirectly. Should only be necessary when you want to return multiple items. The method should view a NULL value passed in to mean that the caller is not interested in one or more returned values.

-(void)getLineDash:(float *)patter count:(int *)count phase:(float *)phase;

Delegate Methods
Delegate methods are those that an object invokes in a delegate if the delegate implements the method when certain events occur. They have a distinctive form, this form also applies to an object’s data source.

-(BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
-(BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;

The class name omits the prefix, the first letter is in lowercase and a colon is affixed to the class name unless the only argument is the sender.

-(BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

Methods that are invoked as a result of a notification are an exception to the above rules. In this case the sole argument is the notification object:

-(void)windowDidChangeScree:(NSNotification *)notification;

Use “did” or “will” for methods that are invoked to notify the delegate that something has happened or is about to happen.

-(void)browserDidScroll:(NSBrowser *)sender;
-(NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;

Although you can use “did” or “will” for methods that are invoked to ask the delegate to do something on behalf of another object, “should” is preferred.

-(BOOL)windowShouldClose:(id)sender;

Collection Methods – NSArray, NSDictionary, NSSet etc.

For objects that manage a collection of objects (each called an element of that collection), the convention is to have methods of the form:

-(void)addElement:(elementType)anObj;
-(void)removeElement:(elementType)anObj;
-(NSArray *)elements;

For example:

-(void)addLayoutManager:(NSLayoutManager *)obj;
-(void)removeLayoutManager:(NSLayoutManager *)obj;
-(NSArray *)layoutManagers;

The following are some qualifications and refinements to this guideline:

If collection is truly unordered, then if possible return an NSSet rather than an NSArray. If it is important to insert elements at at a particular location then instead of or in addition to the ones above:

-(void)insertLayoutManager:(NSLayoutManager *) atIndex:(int)theIndex;
-(void)removeLayoutManagerAtIndex:(int)theIndex;

Collections own objects.

Method Arguments
As with methods, agreements start with a lowercase letter and the first letter of subsequent words are capitalised.

-(void)removeObject:(id)object;

Private methods

In most cases private methods follow the same guidelines as public methods. In apple frameworks private methods are prefixed with an underscore. For this reason any class you design that is a subclass of a Cocoa Framework should not use a underscore to prefix any of its method names as it could easily override private methods of the class you override.

In this case it is sensible to prefix the private methods with the company or project identifier. Two or three uppercase characters followed by an underscore.

-(void)YVS_addObject:(id)theObject;

Naming Functions

If functions belong to a class group then they should start with the same prefix that you use for classes and constants. Function names should follow the camel case convention with the first word being capitalised. Function names should start with a verb that describe what the function does. A couple of examples:

NSHighlightRect
NSDeallocateObject

Functions that get a property from a object should leave out the verb. For example:

unsigned int NSEventMaskFromType(NSEventType type);
float NSSHeight(NSRect aRect);

If a value is returned by reference, use “Get”

const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp);

If the value returned is a boolean then the function should begin with an inflected verb.

BOOL NSDecimalIsNotANumber(const NSDecimal *decimal); // DecimalIs...

Naming properties and data types

If a property is expressed as a noun or a verb, the format is:

@property (strong) NSString *title;
@property (assign) BOOL showsAlpha;

If the name of a declared property is expressed as an adjective, however, the property name omits the is prefix but specifies the conventional name for the get accessor, for example:

@property (assign, getter=isEditable) BOOL editable;

You should not access instance variables directly. You should use the accessor methods. Only in init and dealloc does it make sense to to access instance variables directly.

If you synthesise the instance variable using a declared property, specify the name of the instance variable in the @synthesize statement.

@synthesize showsTitle _showsTitle;

Avoid explicitly declaring instance variables. If you have to declare it then declare using @private or @protected.

Constants whether enumerated or created using the const keyword follow the Function naming pattern. They should start with a prefix that relates to the class the group the constant belongs to, and they should use camel case.

In general don’t use macros for constants.

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. If you misspell the name of the constant symbol you  are likely to get a compile error letting you know.

Notifications are identified by a global NSString objects whose names are composed like so:

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

For example:

NSApplicationDidBecomeActiveNotification

Do not use objective-c exceptions to handle regular, expected error conditions.