Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This document is for the Objective-C and Objective-C++ coding standards at Appcelerator. As with other coding standards documents, the primary goal is clean, readable code, which is comprable to common existing conventions.

Note that we do not encourage specific design patterns or engineering conventions in this document. This is for source code formatting and other sensible conventions; there is a separate document coming for those issues.

Basis for this document

We attempt to follow the Google coding standards and Apple Cocoa guidelines. The remainder of this document reiterates information from these where appropriate, and otherwise provides exceptions to their standards.

...

Always @import (not #import) Objective-C headers, and #include C (or C++) headers.

Class

...

Naming

  • Objective-C classes are to be named with:
    • The prefix Ti, or another project-appropriate prefix
    • Camelcase

...

  • Categories on existing classes should be named appropriately, with the category describing the set of extensions.
  • Categories which are intended to describe a private API within an implementation file should be the empty category ().

ivars

Prefer private properties to ivars. If you do have a valid use case for an ivar, then declare them in the @implementation block (not the @interface block).

Instance variables for a class should be intended one tabstop.

Instance variables should be named in camelcase, and are not required to follow any other specific naming convention. We do recommend that ivars end with an underscore character, and are accessed through property getters rather than directly if possible. The only punctuation considered acceptable in an ivar name is a trailing underscore.

@public, @protected, and @private

Use of access specifiers is discouraged at this time (use publicly-declared and private-category @property instead). In the case that they are used in a class, or this rule is changed, follow the C++ ordering convention of:

  • @public
  • @protected
  • @private

Where the access specifier is not indented (aligned at column 0).

@property and @synthesize

All ivars which are intended to be publicly accessed must have a @property declaration to go with them, which must include nonatomic explicitly if on iOS (optional if on OS X, since not everything needs to be nonatomic there), and either readonly or a storage specifier.

ivars which require @property accessors for internal usage only can have these properties declared as part of a private category.

Naturally every @property is required to have a @synthesize, unless all accessors for it are overloaded. If you write an overloaded setter for a @property you are required to follow the access specifier declared for it.

Use the default synthesis property of ivars. You should rarely need @synthesize.

Methods

  • Methods should be named in camelcase, with the first character lowercase. Method names must never begin with an underscore.
  • The leading method specifier (+ or -) should not be followed by a space, and neither should the return type.
  • Selector (and argument) names should not have a space after their : character, or the type.
  • If method declarations, definitions, or calls are spread across multiple lines, their : characters should be aligned rather than spaced on tabstops.
  • The opening brace of a method should be on its own line for implementations.
Code Block
titleExample
+(void)x:(int)y
{
}

-(void)veryLongMethodName:(NSObject*)veryLongArgumentName
                     arg2:(NSObject*)anotherArg
                     arg3:(NSObject*)moreArg
{
}

init

Every class must have

...

one, and only one, designated initializer

...

that is identified as such in a comment. The following is

...

an example of well-written designated initializer:

Code Block
titleExample
// Designated initializer.
-(idinstancetype)init
{
    if (	self = [super init];
    if (self) {
        // initialization code goes here...
    }
    return self;
}

Note the single braces. You may wish to turn off the "initializer not fully bracketed" clang warning in Xcode as a result.

...

Prefer fast enumeration loops to other looping constructs where possible. Note that if y is a method call, the result of it should be pre-cached. Do not write fast enumeration loops which would modify y (whether an object or a method call) as a side-effect of the loop contents.

Objective-C++

All of the rules for Objective-C apply to Objective-C++ as well.

The only formal rule we have regarding Objective-C++ at this time is that you should intend to avoid using it. Unless your source explicitly includes or references C++ classes, or must make use of a C++ header that is not extern "C" (which should never, ever happen - that is a bug in the C++ header) you should not tag your file with the .mm extension - this prevents useful XCode features such as refactoring (XCode refuses to refactor C++ code, wisely) and increases compilation time (a C++ compiler must be invoked instead of a C compiler).

To reiterate: Do not use Objective-C++ file designators unless you are absolutely certain the code you have written is in Objective-C++, and cannot be compiled by a C compiler. It leads to very serious bugs that only show up during linking.

File names

The following file names are acceptable for Objective-C:

...