- Dot-Notation Syntax
- Spacing
- Conditionals
- Error handling
- Methods
- Variables
- Naming
- Comments
- Init & Dealloc
- Literals
- CGRect Functions
- Constants
- Enumerated Types
- Bitmasks
- Private Properties
- Pragma Marks
- Arithmetic and Comparison Operators
- Other Spacing
- Property Declarations
- Header Imports
- Method Ordering and Grouping
- Image Naming
- Booleans
- Singletons
- Xcode Project
Dot-notation should always be used for accessing and mutating properties. Bracket notation is preferred in all other instances.
For example:
view.backgroundColor = [UIColor orangeColor];
[UIApplication sharedApplication].delegate;
count = myArray.count;
length = myName.length;
Not:
[view setBackgroundColor:[UIColor orangeColor]];
UIApplication.sharedApplication.delegate;
count = [myArray count];
length = [myName length];
- Indent using 4 spaces. Never indent with tabs. Be sure to set this preference in Xcode.
- Method braces and other braces (
if
/else
/switch
/while
etc.) always open on the same line as the statement.
For example:
if (user.isHappy) {
//Do something
} else {
//Do something else
}
- There should be exactly one blank line between methods to aid in visual clarity and organization. Whitespace within methods should separate functionality, but often there should probably be new methods.
@synthesize
and@dynamic
should be grouped logically, each group to be declared on new lines in the implementation.
Conditional bodies should always use braces even when a conditional body could be written without braces (e.g., it is one line only) to prevent errors.
For example:
if (!error) {
return success;
}
Not:
if (!error)
return success;
or
if (!error) return success;
There should be a space either side of the outer most brackets.
For example:
if (!error) {
return success;
}
Not:
if(!error){
return success;
}
or:
if (!error){
return success;
}
The Ternary operator, ? , should never be used.
For example:
NSUInteger result;
if (a > b) {
result = x;
} else {
result = y;
}
Not:
NSUInteger result = a > b ? x : y;
When methods return an error parameter by reference, switch on the returned value, not the error variable.
For example:
NSError *error;
if (![self trySomethingWithError:&error]) {
// Handle Error
}
Not:
NSError *error;
[self trySomethingWithError:&error];
if (error) {
// Handle Error
}
Some of Apple’s APIs write garbage values to the error parameter (if non-NULL) in successful cases, so switching on the error can cause false negatives (and subsequently crash).
*In method signatures, there should be a space after the scope (-/+ symbol). There should be a space between the method segments. *There should be no space after the method's return type declaration. *There should be no space after colons in the method signature. *There should be no space after the parameter type in the method signature. *The open brace should be on a new line. *When calling methods there should be no space after semicolons.
For example::
- (void)setExampleText:(NSString *)text image:(UIImage *)image;
Not::
-(void) setExampleText: (NSString *)text image:(UIImage *) image;
Variables should be named as descriptively as possible. Single letter variable names should be avoided. Even in for()
loops, you can use something like beanCounter
rather than just i
.
Asterisks indicating pointers belong with the variable.
For example:
NSString *text;
Not:
NSString* text;
or:
NSString * text;
Property definitions should be used in place of naked instance variables whenever possible. Direct instance variable access should be avoided except in initializer methods (`init`, `initWithCoder:`, etc…), `dealloc` methods and within custom setters and getters. For more information on using Accessor Methods in Initializer Methods and dealloc, see [here](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html#//apple_ref/doc/uid/TP40004447-SW6).
**For example:**
```objc
@interface NYTSection: NSObject
@property (nonatomic) NSString *headline;
@end
Not:
@interface NYTSection : NSObject {
NSString *headline;
}
When it comes to the variable qualifiers introduced with ARC, the qualifier (__strong
, __weak
, __unsafe_unretained
, __autoreleasing
__block
) should be placed on the left of the class name.
For example:
__block NSString *text
Apple naming conventions should be adhered to wherever possible, especially those related to memory management rules (NARC).
Long, descriptive method and variable names are good.
For example:
UIButton *settingsButton;
Not:
UIButton *setBut;
Constants should be camel-case with all words capitalized and prefixed by the related class name for clarity. Constants and variables should never be abbreviated.
For example:
static const NSTimeInterval ArticleViewControllerNavigationFadeAnimationDuration = 0.3;
Not:
static const NSTimeInterval AVCFadeTime = 1.7;
or:
static const NSTimeInterval fadetime = 1.7;
Properties and local variables should be camel-case with the leading word being lowercase.
Instance variables should be camel-case with the leading word being lowercase, and should be prefixed with an underscore. This is consistent with instance variables synthesized automatically by LLVM. If LLVM can synthesize the variable automatically, then let it.
For example:
@synthesize descriptiveVariableName = _descriptiveVariableName;
Not:
id varnm;
When they are needed, comments should be used to explain why a particular piece of code does something. Any comments that are used must be kept up-to-date or deleted.
Block comments should generally be avoided, as code should be as self-documenting as possible, with only the need for intermittent, few-line explanations. This does not apply to those comments used to generate documentation.
dealloc
methods should be placed at the top of the implementation, directly after the @synthesize
and @dynamic
statements. init
should be placed directly below the dealloc
methods of any class.
init
methods should be structured like this:
- (instancetype)init
{
self = [super init]; // or call the designated initalizer
if (self) {
// Custom initialization
}
return self;
}
NSString
, NSDictionary
, NSArray
, and NSNumber
literals should be used whenever creating immutable instances of those objects. Pay special care that nil
values not be passed into NSArray
and NSDictionary
literals, as this will cause a crash.
NSNumber literals should use brackets to encode numeric values, this is not necessary for boolean (YES
/`NO) values.
There should always be space after each comma, either side of each semicolon and on the inside of the encasing brace or squared bracket.
For example:
NSArray *names = @[ @"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul" ];
NSDictionary *productManagers = @{ @"iPhone" : @"Kate", @"iPad" : @"Kamal", @"Mobile Web" : @"Bill" };
NSNumber *shouldUseLiterals = @YES;
NSNumber *buildingZIPCode = @(10018.22);
Not:
NSArray *names = [NSArray arrayWithObjects:@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul", nil];
NSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys: @"Kate", @"iPhone", @"Kamal", @"iPad", @"Bill", @"Mobile Web", nil];
NSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];
NSNumber *buildingZIPCode = [NSNumber numberWithInteger:10018];
When accessing the x
, y
, width
, or height
of a CGRect
, always use the CGGeometry
functions instead of direct struct member access. From Apple's CGGeometry
reference:
All functions described in this reference that take CGRect data structures as inputs implicitly standardize those rectangles before calculating their results. For this reason, your applications should avoid directly reading and writing the data stored in the CGRect data structure. Instead, use the functions described here to manipulate rectangles and to retrieve their characteristics.
For example:
CGRect frame = self.view.frame;
CGFloat x = CGRectGetMinX(frame);
CGFloat y = CGRectGetMinY(frame);
CGFloat width = CGRectGetWidth(frame);
CGFloat height = CGRectGetHeight(frame);
Not:
CGRect frame = self.view.frame;
CGFloat x = frame.origin.x;
CGFloat y = frame.origin.y;
CGFloat width = frame.size.width;
CGFloat height = frame.size.height;
Constants are preferred over in-line string literals or numbers, as they allow for easy reproduction of commonly used variables and can be quickly changed without the need for find and replace. Constants should be declared as static
constants and not #define
s unless explicitly being used as a macro.
For example:
static NSString * const AboutViewControllerCompanyName = @"The New York Times Company";
static const CGFloat ImageThumbnailHeight = 50.0;
Not:
#define CompanyName @"The New York Times Company"
#define thumbnailHeight 2
When using enum
s, it is recommended to use the new fixed underlying type specification because it has stronger type checking and code completion. The SDK now includes a macro to facilitate and encourage use of fixed underlying types — NS_ENUM()
Example:
typedef NS_ENUM(NSInteger, AdRequestState) {
AdRequestStateInactive,
RequestStateLoading
};
When working with bitmasks, use the NS_OPTIONS
macro.
Example:
typedef NS_OPTIONS(NSUInteger, NYTAdCategory) {
NYTAdCategoryAutos = 1 << 0,
NYTAdCategoryJobs = 1 << 1,
NYTAdCategoryRealState = 1 << 2,
NYTAdCategoryTechnology = 1 << 3
};
Private properties should be declared in class extensions (anonymous categories) in the implementation file of a class. Named categories (such as private
) should never be used unless extending another class.
For example:
@interface Advertisement ()
@property (nonatomic, strong) GADBannerView *googleAdView;
@property (nonatomic, strong) ADBannerView *iAdView;
@property (nonatomic, strong) UIWebView *adXWebView;
@end
There should be two newlines above a #pragma mark
and one newline below. There should be no space after the hash
. They should be used to categorise similar methods and use a title to describe what the category of methods does. The dash with a space either side is used to display a separator in Xcode's method selector.
For example:
#pragma mark - View Lifecycle Methods
Each arithmetic and comparison operator should have a space either side of it, brackets should be used for clarity even when unnecessary.
For example:
NSUInteger random = smallest + arc4random() % (largest + 1 - smallest);
Not:
NSUInteger random = smallest +arc4random() %(largest +1-smallest);
-
There should be a space before and after the equals operator when assigning values to properties.
-
There should only be one newline before @end.
-
There should be a newline before the return when the method isn't a single line.
-
There should be one newline between methods.
-
There should be a space before the protocol declaration list.
AppDelegate : UIResponder <UIApplicationDelegate>
-
There should be no space before the colon in the case declaration of a switch statement.
-
There should always be a space before the asterisk in method signature and variable declarations.
- The order should be strong, nonatomic.
- There should be a space on either side of the brackets.
- There should be a space after each comma.
- Properties should be grouped together when they are similar with newline gaps between groups.
There should be a grouping order to header imports for clarity:
- Working file's header
- Frameworks
- Categories
- Singeltons
- View Controllers
- Cells
- Controls
- Models
Methods should be in the same order in the interface as they are in the implementation. Methods should be groups in there interface in the same way as they are in the implementation (by #pragma mark) though no #pragma mark is needed.
Image names should be named consistently to preserve organization and developer sanity. They should be named as one camel case string with a description of their purpose, followed by the un-prefixed name of the class or property they are customizing (if there is one), followed by a further description of color and/or placement, and finally their state.
For example:
RefreshBarButtonItem
/RefreshBarButtonItem@2x
andRefreshBarButtonItemSelected
/RefreshBarButtonItemSelected@2x
ArticleNavigationBarWhite
/ArticleNavigationBarWhite@2x
andArticleNavigationBarBlackSelected
/ArticleNavigationBarBlackSelected@2x
.
Images that are used for a similar purpose should be grouped in respective groups in an Images folder.
Since nil
resolves to NO
it is unnecessary to compare it in conditions. Never compare something directly to YES
, because YES
is defined to 1 and a BOOL
can be up to 8 bits.
This allows for more consistency across files and greater visual clarity.
For example:
if (!someObject) {
}
Not:
if (someObject == nil) {
}
For a BOOL
, here are two examples:
if (isAwesome)
if (![someObject boolValue])
Not:
if ([someObject boolValue] == NO)
if (isAwesome == YES) // Never do this.
If the name of a BOOL
property is expressed as an adjective, the property can omit the “is” prefix but specifies the conventional name for the get accessor.
For example:
@property (assign, getter=isEditable) BOOL editable;
Text and example taken from the Cocoa Naming Guidelines.
Singleton objects should use a thread-safe pattern for creating their shared instance.
For example:
+ (instancetype)sharedInstance
{
static id sharedInstance = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
sharedInstance = [[self alloc] init];
});
return sharedInstance;
}
This will prevent possible and sometimes prolific crashes.
The physical files should be kept in sync with the Xcode project files in order to avoid file sprawl. Any Xcode groups created should be reflected by folders in the filesystem. Code should be grouped not only by type, but also by feature for greater clarity.
When possible, always turn on "Treat Warnings as Errors" in the target's Build Settings and enable as many additional warnings as possible. If you need to ignore a specific warning, use Clang's pragma feature.