Download - Coding Conventions Objective-C
-
8/2/2019 Coding Conventions Objective-C
1/23
Coding conventions Objective-C
1. BackgroundObjective-C is a very dynamic, object-oriented extension of C. It's designed to be
easy to use and read, while enabling sophisticated object-oriented design. It is the
primary development language for new applications on Mac OS X and the iPhone.
Cocoa is one of the main application frameworks on Mac OS X. It is a collection of
Objective-C classes that provide for rapid development of full-featured Mac OS X
applications.
2. ExampleThey say an example is worth a thousand words so let's start off with an example
that should give you a feel for the style, spacing, naming, etc.
An example header file, demonstrating the correct commenting and spacing for
an @interface declaration
//
// Foo.m// AwesomeProject
//
// Created by Benjamin HALIMI on 25/03/2012.
// Copyright 2012 Snapkeys, Inc. All rights reserved.
//
#import
// A sample class demonstrating good Objective-C style. All interfaces,
// categories, and protocols (read: all top-level declarations in a header)// MUST be commented. Comments must also be adjacent to the object they're
// documenting.
//
// (no blank line between this comment and the interface)
@interface Foo : NSObject {
@private
NSString *bar_;
NSString *bam_;
}
// Returns an autoreleased instance of Foo. See -initWithBar: for details
-
8/2/2019 Coding Conventions Objective-C
2/23
// about |bar|.
+ (id)fooWithBar:(NSString *)bar;
// Designated initializer. |bar| is a thing that represents a thing that
// does a thing.
- (id)initWithBar:(NSString *)bar;
// Gets and sets |bar_|.
- (NSString *)bar;
- (void)setBar:(NSString *)bar;
// Does some work with |blah| and returns YES if the work was completed
// successfully, and NO otherwise.
- (BOOL)doWorkWithBlah:(NSString *)blah;
@end
An example source file, demonstrating the correct commenting and spacing for
the @implementation of an interface. It also includes the reference
implementations for important methods like getters and setters, init, and dealloc.
//
// Foo.m
// AwesomeProject
//// Created by Benjamin HALIMI on 25/03/2012.
// Copyright 2012 Snapkeys, Inc. All rights reserved.
//
#import "Foo.h"
@implementation Foo
+ (id)fooWithBar:(NSString *)bar {return [[[self alloc] initWithBar:bar] autorelease];
}
// Must always override super's designated initializer.
- (id)init {
return [self initWithBar:nil];
}
- (id)initWithBar:(NSString *)bar {
if ((self = [super init])) {
-
8/2/2019 Coding Conventions Objective-C
3/23
bar_ = [bar copy];
bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
}
return self;
}
- (void)dealloc {
[bar_ release];
[bam_ release];
[super dealloc];
}
- (NSString *)bar {
return bar_;
}
- (void)setBar:(NSString *)bar {
[bar_ autorelease];
bar_ = [bar copy];
}
- (BOOL)doWorkWithBlah:(NSString *)blah {
// ...
return NO;
}
@end
Blank lines before and after @interface, @implementation, and @end are
optional. If your @interface declares instance variables, a blank line should come
after the closing brace (}).
Unless an interface or implementation is very short, such as when declaring a
handful of private methods or a bridge class, adding blank lines usually helps
readability.
3. Spacing And Formatting Spaces vs. Tabs
Use only spaces, and indent 2 spaces at a time.
We use spaces for indentation. Do not use tabs in your code. You should set your
editor to emit spaces when you hit the tab key.
-
8/2/2019 Coding Conventions Objective-C
4/23
Line LengthEach line of text in your code should try to be at most 80 characters long.
Strive to keep your code within 80 columns. We realize that Objective C is a
verbose language and in some cases it may be more readable to extend slightly
beyond 80 columns, but this should definitely be the exception and not
commonplace.
If a reviewer asks that you reformat a line because they feel it can be fit in 80
columns and still be readable, you should do so.
We recognize that this rule is controversial, but so much existing code already
adheres to it, and we feel that consistency is important.
You can make violations easier to spot in Xcode by going toXcode > Preferences >
Text Editing > Show page guide.
Method Declarations and DefinitionsOne space should be used between the - or + and the return type, and no spacing
in the parameter list except between parameters.
Methods should look like this:
- (void)doSomethingWithString:(NSString *)theString {
}
The spacing before the asterisk is optional. When adding new code, be consistent
with the surrounding file's style.
If you have too many parameters to fit on one line, giving each its own line ispreferred. If multiple lines are used, align each using the colon before the
parameter.
- (void)doSomethingWith:(GTMFoo *)theFoo
rect:(NSRect)theRect
interval:(float)theInterval {
...
}
When the first keyword is shorter than the others, indent the later lines by atleast four spaces. You can do this by making keywords line up vertically, not
aligning colons:
- (void)short:(GTMFoo *)theFoo
longKeyword:(NSRect)theRect
evenLongerKeyword:(float)theInterval {
...
}
-
8/2/2019 Coding Conventions Objective-C
5/23
Method InvocationsMethod invocations should be formatted much like method declarations. When
there's a choice of formatting styles, follow the convention already used in a given
source file.
Invocations should have all arguments on one line:
[myObject doFooWith:arg1 name:arg2 error:arg3];
or have one argument per line, with colons aligned:
[myObject doFooWith:arg1
name:arg2
error:arg3];
Don't use any of these styles:
[myObject doFooWith:arg1 name:arg2 // some lines with >1 arg
error:arg3];
[myObject doFooWith:arg1
name:arg2 error:arg3];
[myObject doFooWith:arg1
name:arg2 // aligning keywords instead of colons
error:arg3];
As with declarations and definitions, when the keyword lengths make it
impossible to align colons and still have four leading spaces, indent later lines by
four spaces and align keywords after the first one, instead of aligning the colons.
[myObj short:arg1
longKeyword:arg2
evenLongerKeyword:arg3];
@public and @privateThe @public and @private access modifiers should be indented by 1 space.
This is similar to public, private, and protected in C++.
@interface MyClass : NSObject {
@public
...
@private
...
}@end
-
8/2/2019 Coding Conventions Objective-C
6/23
ExceptionsFormat exceptions with each @ label on its own line and a space between the @
label and the opening brace ({), as well as between the @catch and the caught
object declaration.
@try {
foo();
}
@catch (NSException *ex) {
bar(ex);
}
@finally {
baz();
}
ProtocolsThere should not be a space between the type identifier and the name of the
protocol encased in angle brackets.
This applies to class declarations, instance variables, and method declarations.
For example:
@interface MyProtocoledClass : NSObject {
@privateid delegate_;
}
- (void)setDelegate:(id)aDelegate;
@end
BlocksBlocks are preferred to the target-selector pattern when creating callbacks, as it
makes code easier to read. Code inside blocks should be indented four spaces.
There are several appropriate style rules, depending on how long the block is: If the block can fit on one line, no wrapping is necessary. If it has to wrap, the closing brace should line up with the first character of
the line on which the block is declared.
Code within the block should be indented four spaces. If the block is large, e.g. more than 20 lines, it is recommended to move it
out-of-line into a local variable.
If the block takes no parameters, there are no spaces between thecharacters ^{. If the block takes parameters, there is no space between the
^( characters, but there is one space between the ) { characters.
-
8/2/2019 Coding Conventions Objective-C
7/23
Two space indents inside blocks are also allowed, but should only be usedwhen it's consistent with the rest of the project's code.
// The entire block fits on one line.
[operation setCompletionBlock:^{ [self onOperationDone]; }];
// The block can be put on a new line, indented four spaces, with the
// closing brace aligned with the first character of the line on which
// block was declared.
[operation setCompletionBlock:^{
[self.delegate newDataAvailable];
}];
// Using a block with a C API follows the same alignment and spacing
// rules as with Objective-C.dispatch_async(fileIOQueue_, ^{
NSString* path = [self sessionFilePath];
if (path) {
// ...
}
});
// An example where the parameter wraps and the block declaration fits
// on the same line. Note the spacing of |^(SessionWindow *window) {|
// compared to |^{| above.[[SessionService sharedService]
loadWindowWithCompletionBlock:^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}
}];
// An example where the parameter wraps and the block declaration does// not fit on the same line as the name.
[[SessionService sharedService]
loadWindowWithCompletionBlock:
^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}}];
-
8/2/2019 Coding Conventions Objective-C
8/23
// Large blocks can be declared out-of-line.
void (^largeBlock)(void) = ^{
// ...
};
[operationQueue_ addOperationWithBlock:largeBlock];
4. Naming File Names
File names should reflect the name of the class implementation that they contain -
- including case. Follow the convention that your project uses.
File extensions should be as follows:
.h C/C++/Objective-C header file
.m Objective-C implementation file
.mmObjective-C++ implementation
file
.cc Pure C++ implementation file
.c C implementation file
File names for categories should include the name of the class being extended, e.g.
GTMNSString+Utils.h or GTMNSTextView+Autocomplete.h
Objective-C++Within a source file, Objective-C++ follows the style of the function/method
you're implementing.
In order to minimize clashes between the differing naming styles when mixing
Cocoa/Objective-C and C++, follow the style of the method being implemented. If
you're in an @implementation block, use the Objective-C naming rules. If you're
implementing a method for a C++ class, use the C++ naming rules.
// file: cross_platform_header.h
class CrossPlatformAPI {
public:
...
int DoSomethingPlatformSpecific(); // impl on each platform
private:
int an_instance_var_;
};
// file: mac_implementation.mm
-
8/2/2019 Coding Conventions Objective-C
9/23
#include "cross_platform_header.h"
// A typical Objective-C class, using Objective-C naming.
@interface MyDelegate : NSObject {
@private
int instanceVar_;
CrossPlatformAPI* backEndObject_;
}
- (void)respondToSomething:(id)something;
@end
@implementation MyDelegate
- (void)respondToSomething:(id)something {
// bridge from Cocoa through our C++ backend
instanceVar_ = backEndObject->DoSomethingPlatformSpecific();
NSString* tempString = [NSString stringWithInt:instanceVar_];NSLog(@"%@", tempString);
}
@end
// The platform-specific implementation of the C++ class, using
// C++ naming.
int CrossPlatformAPI::DoSomethingPlatformSpecific() {
NSString* temp_string = [NSString stringWithInt:an_instance_var_];
NSLog(@"%@", temp_string);
return [temp_string intValue];}
Class NamesClass names (along with category and protocol names) should start as uppercase
and use mixed case to delimit words.
In application-levelcode, prefixes on class names should generally be avoided.
Having every single class with same prefix impairs readability for no benefit.
When designing code to be shared across multiple applications, prefixes are
acceptable and recommended (e.g. GTMSendMessage).
Category NamesCategory names should start with a 2 or 3 character prefix identifying the
category as part of a project or open for general use. The category name should
incorporate the name of the class it's extending.
For example, if we want to create a category on NSString for parsing, we would
put the category in a file named GTMNSString+Parsing.h, and the category itself
would be named GTMStringParsingAdditions (yes, we know the file name and the
category name do not match, but this file could have many separate categoriesrelated to parsing). Methods in that category should share the prefix
-
8/2/2019 Coding Conventions Objective-C
10/23
(gtm_myCategoryMethodOnAString:) in order to prevent collisions in Objective-C
which only has a single namespace. If the code isn't meant to be shared and/or
doesn't run in a different address-space, the method naming isn't quite as
important.
There should be a single space between the class name and the opening
parenthesis of the category.
Objective-C Method NamesMethod names should start as lowercase and then use mixed case. Each named
parameter should also start as lowercase.
Accessor methods should be named the same as the variable they're "getting", but
they should notbe prefixed with the word "get". For example:
- (id)getDelegate; // AVOID
- (id)delegate; // GOOD
Variable NamesVariables names start with a lowercase and use mixed case to delimit words.
Class member variables have trailing underscores. For example: myLocalVariable,
myInstanceVariable_. Members used for KVO/KVC bindings may begin with a
leading underscore iffuse of Objective-C 2.0's @property isn't allowed.
Common Variable Names
Do notuse Hungarian notation for syntactic attributes, such as the static type of avariable (int or pointer). Give as descriptive a name as possible, within reason.
Don't worry about saving horizontal space as it is far more important to make
your code immediately understandable by a new reader. For example:
int w;
int nerr;
int nCompConns;
tix = [[NSMutableArray alloc] init];
obj = [someObject object];
p = [network port];
int numErrors;
int numCompletedConnections;
tickets = [[NSMutableArray alloc] init];
userInfo = [someObject object];
port = [network port];
Instance Variables
Instance variables are mixed case and should be suffixed with a trailingunderscore, e.g. usernameTextField_. However, we permit an exception when
-
8/2/2019 Coding Conventions Objective-C
11/23
binding to a member variable using KVO/KVC and Objective-C 2.0 cannot be used
(due to OS release constraints). In this case, it is acceptable to prefix the variable
with an underscore, per Apple's accepted practices for key/value naming. If
Objective-C 2.0 can be used, @property and @synthesize provide a solution that
conforms to the naming guidelines.
Constants
Constant names (#defines, enums, const local variables, etc.) should start with a
lowercase kand then use mixed case to delimit words, i.e. kInvalidHandle,
kWritePerm.
5. Comments File Comments
Start each file with a basic description of the contents of the file, followed by an
author, and then followed by a copyright notice and/or license boilerplate.
Legal Notice and Author Line
Every file should contain the following items, in order:
a basic description of the contents of the file an author line
a copyright statement (for example, Copyright 2012 Snapkeys Inc.) license boilerplate if neccessary. Choose the appropriate boilerplate for the
license used by the project (e.g. Apache 2.0, BSD, LGPL, GPL)
If you make significant changes to a file that someone else originally wrote, add
yourself to the author line. This can be very helpful when another contributor has
questions about the file and needs to know whom to contact about it.
Declaration CommentsEvery interface, category, and protocol declaration should have an accompanyingcomment describing its purpose and how it fits into the larger picture.
// A delegate for NSApplication to handle notifications about app
// launch and shutdown. Owned by the main app controller.
@interface MyAppDelegate : NSObject {
...
}
@end
-
8/2/2019 Coding Conventions Objective-C
12/23
If you have already described an interface in detail in the comments at the top of
your file feel free to simply state "See comment at top of file for a complete
description", but be sure to have some sort of comment.
Additionally, each method in the public interface should have a comment
explaining its function, arguments, return value, and any side effects.
Document the synchronization assumptions the class makes, if any. If an instance
of the class can be accessed by multiple threads, take extra care to document the
rules and invariants surrounding multithreaded use.
Implementation CommentsUse vertical bars to quote variable names and symbols in comments rather than
quotes or naming the symbol inline.
This helps eliminate ambiguity, especially when the symbol is a common word
that might make the sentence read like it was poorly constructed. E.g. for a
symbol "count":
// Sometimes we need |count| to be less than zero.
or when quoting something which already contains quotes
// Remember to call |StringWithoutSpaces("foo bar baz")|
Object OwnershipMake the pointer ownership model as explicit as possible when it falls outside themost common Objective-C usage idioms.
Instance variables which are pointers to objects derived from NSObject are
presumed to be retained, and should be either commented as weak or declared
with the __weak lifetime qualifier when applicable. Similarly, declared properties
must specify a weak or assign property attribute if they are not retained by the
class. An exception is instance variables labeled as IBOutlets in Mac software,
which are presumed to not be retained.
Where instance variables are pointers to CoreFoundation, C++, and other non-
Objective-C objects, they should always be declared with the __strong and __weak
type modifiers to indicate which pointers are and are not retained.
CoreFoundation and other non-Objective-C object pointers require explicit
memory management, even when building for automatic reference counting or
garbage collection. When the __weak type modifier is not allowed (e.g. C++
member variables when compiled under clang), a comment should be used
instead.
Examples of strong and weak declarations:
@interface MyDelegate : NSObject {
@private
-
8/2/2019 Coding Conventions Objective-C
13/23
IBOutlet NSButton *okButton_; // normal NSControl; implicitly weak on Mac
only
AnObjcObject* doohickey_; // my doohickey
__weak MyObjcParent *parent_; // so we can send msgs back (owns me)
// non-NSObject pointers...
__strong CWackyCPPClass *wacky_; // some cross-platform object
__strong CFDictionaryRef *dict_;
}
@property(strong, nonatomic) NSString *doohickey;
@property(weak, nonatomic) NSString *parent;
@end
6. Cocoa and Objective-C Features Member Variables Should Be @private
Member variables should be declared @private.
@interface MyClass : NSObject {
@private
id myInstanceVariable_;
}// public accessors, setter takes ownership
- (id)myInstanceVariable;
- (void)setMyInstanceVariable:(id)theVar;
@end
Identify Designated InitializerComment and clearly identify your designated initializer.
It is important for those who might be subclassing your class that the designated
initializer be clearly identified. That way, they only need to subclass a singleinitializer (of potentially several) to guarantee their subclass' initializer is called.
It also helps those debugging your class in the future understand the flow of
initialization code if they need to step through it.
Override Designated InitializerWhen writing a subclass that requires an init... method, make sure you override
the superclass' designated initializer.
If you fail to override the superclass' designated initializer, your initializer may
not be called in all cases, leading to subtle and very difficult to find bugs.
-
8/2/2019 Coding Conventions Objective-C
14/23
Overridden NSObject Method PlacementIt is strongly recommended and typical practice to place overridden methods of
NSObjectat the top of an @implementation.
This commonly applies (but is not limited) to the init..., copyWithZone:, and
dealloc methods. init... methods should be grouped together, followed by the
copyWithZone: method, and finally the dealloc method.
InitializationDon't initialize variables to 0 or nil in the init method; it's redundant.
All memory for a newly allocated object is initialized to 0 (except for isa), so don't
clutter up the initmethod by re-initializing variables to 0 or nil.
Avoid +newDo not invoke the NSObjectclass method new, nor override it in a subclass.Instead, use alloc and initmethods to instantiate retained objects.
Modern Objective-C code explicitly calls alloc and an initmethod to create and
retain an object. As the new class method is rarely used, it makes reviewing code
for correct memory management more difficult.
Keep the Public API SimpleKeep your class simple; avoid "kitchen-sink" APIs. If a method doesn't need to be
public, don't make it so. Use a private category to prevent cluttering the public
header.Unlike C++, Objective-C doesn't have a way to differentiate between public and
private methods everything is public. As a result, avoid placing methods in the
public API unless they are actually expected to be used by a consumer of the class.
This helps reduce the likelihood they'll be called when you're not expecting it.
This includes methods that are being overridden from the parent class. For
internal implementation methods, use a category defined in the implementation
file as opposed to adding them to the public header.
// GTMFoo.m
#import "GTMFoo.h"
@interface GTMFoo (PrivateDelegateHandling)
- (NSString *)doSomethingWithDelegate; // Declare private method
@end
@implementation GTMFoo(PrivateDelegateHandling)
...
- (NSString *)doSomethingWithDelegate {
// Implement this method
}
-
8/2/2019 Coding Conventions Objective-C
15/23
...
@end
Before Objective-C 2.0, if you declare a method in the private @interface, but
forget to implement it in the main @implementation, the compiler will notobject.
(This is because you don't implement these private methods in a separate
category.) The solution is to put the functions within an @implementation that
specifies the category.
Again, "private" methods are not really private. You could accidentally override a
superclass's "private" method, thus making a very difficult bug to squash. In
general, private methods should have a fairly unique name that will prevent
subclasses from unintentionally overriding them.
Finally, Objective-C categories are a great way to segment a large
@implementation section into more understandable chunks and to add new,
application-specific functionality to the most appropriate class. For example,instead of adding "middle truncation" code to a random object in your app, make
a new category on NSString).
#import and #include#importObjective-C/Objective-C++ headers, and #include C/C++ headers.
Choose between #importand #include based on the language of the header that
you are including.
When including a header that uses Objective-C or Objective-C++, use#import.
When including a standard C or C++ header, use #include.Some Objective-C headers lack#define guards, and expect to be included only by
#import. As Objective-C headers may only be included in Objective-C source files
and other Objective-C headers, using #import across the board is appropriate.
Standard C and C++ headers without any Objective-C in them can expect to be
included by ordinary C and C++ files. Since there is no #importin standard C or
C++, such files will be included by #include in those cases. Using #include for
them in Objective-C source files as well means that these headers will always be
included with the same semantics.This rule helps avoid inadvertent errors in cross-platform projects. A Mac
developer introducing a new C or C++ header might forget to add #define guards,
which would not cause problems on the Mac if the new header were included
with #import, but would break builds on other platforms where #include is used.
Being consistent by using #include on all platforms means that compilation is
more likely to succeed everywhere or fail everywhere, and avoids the frustration
of files working only on some platforms.
#import
#include #import "GTMFoo.h"
-
8/2/2019 Coding Conventions Objective-C
16/23
#include "base/basictypes.h"
Use Root FrameworksInclude root frameworks over individual files.
While it may seem tempting to include individual system headers from aframework such as Cocoa or Foundation, in fact it's less work on the compiler if
you include the top-level root framework. The root framework is generally pre-
compiled and can be loaded much more quickly. In addition, remember to use
#import rather than #include for Objective-C frameworks.
#import // good
#import // avoid
#import
...
Prefer To autorelease At Time of CreationWhen creating new temporary objects, autorelease them on the same line as you
create them rather than a separate release later in the same method.
While ever so slightly slower, this prevents someone from accidentally removing
the release or inserting a return before it and introducing a memory leak. E.g.:
// AVOID (unless you have a compelling performance reason)
MyController* controller = [[MyController alloc] init];
// ... code here that might return ...[controller release];
// BETTER
MyController* controller = [[[MyController alloc] init] autorelease];
Autorelease Then RetainAssignment of objects follows the autorelease then retain pattern.
When assigning a new object to a variable, one must first release the old object to
avoid a memory leak. There are several "correct" ways to handle this. We'vechosen the "autorelease then retain" approach because it's less prone to error. Be
aware in tight loops it can fill up the autorelease pool, and may be slightly less
efficient, but we feel the tradeoffs are acceptable.
- (void)setFoo:(GMFoo *)aFoo {
[foo_ autorelease]; // Won't dealloc if |foo_| == |aFoo|
foo_ = [aFoo retain];
}
-
8/2/2019 Coding Conventions Objective-C
17/23
Avoid Accessors During init and deallocInstance subclasses may be in an inconsistent state during initand dealloc
method execution, so code in those methods should avoid invoking accessors.
Subclasses have not yet been initialized or have already deallocated when init
and dealloc methods execute, making accessor methods potentially unreliable.
Whenever practical, directly assign to and release ivars in those methods rather
than rely on accessors.
- (id)init {
self = [super init];
if (self) {
bar_ = [[NSMutableString alloc] init]; // good
}
return self;
}
- (void)dealloc {
[bar_ release]; // good
[super dealloc];
}
- (id)init {
self = [super init];
if (self) {
self.bar = [NSMutableString string]; // avoid}
return self;
}
- (void)dealloc {
self.bar = nil; // avoid
[super dealloc];
}
Dealloc Instance Variables in Declaration Orderdealloc should process instance variables in the same order the @interface
declares them, so it is easier for a reviewer to verify.
A code reviewer checking a new or revised dealloc implementation needs to
make sure that every retained instance variable gets released.
To simplify reviewing dealloc, order the code so that the retained instance
variables get released in the same order that they are declared in the @interface.
Ifdealloc invokes other methods that release instance variables, add comments
describing what instance variables those methods handle.
-
8/2/2019 Coding Conventions Objective-C
18/23
Setters copy NSStringsSetters taking an NSString, should always copy the string it accepts.
Never justretain the string. This avoids the caller changing it under you without
your knowledge. Don't assume that because you're accepting an NSString that it's
not actually an NSMutableString.
- (void)setFoo:(NSString *)aFoo {
[foo_ autorelease];
foo_ = [aFoo copy];
}
Avoid Throwing ExceptionsDon't@throw Objective-C exceptions, but you should be prepared to catch them
from third-party or OS calls.
We do compile with -fobjc-exceptions (mainly so we get@synchronized), but we
don't@throw. Use of@try, @catch, and @finally are allowed when required to
properly use 3rd party code or libraries. If you do use them please document
exactly which methods you expect to throw.
Do not use the NS_DURING, NS_HANDLER, NS_ENDHANDLER, NS_VALUERETURN
and NS_VOIDRETURN macros unless you are writing code that needs to run on
Mac OS X 10.2 or before.
Also be aware when writing Objective-C++ code that stack based objects are not
cleaned up when you throw an Objective-C exception. Example:
class exceptiontest {
public:
exceptiontest() { NSLog(@"Created"); }
~exceptiontest() { NSLog(@"Destroyed"); }
};
void foo() {
exceptiontest a;
NSException *exception = [NSException exceptionWithName:@"foo"
reason:@"bar"userInfo:nil];
@throw exception;
}
int main(int argc, char *argv[]) {
GMAutoreleasePool pool;
@try {
foo();
}
@catch(NSException *ex) {NSLog(@"exception raised");
-
8/2/2019 Coding Conventions Objective-C
19/23
}
return 0;
}
will give you:
2012-03-25 12:34:29.244 exceptiontest[23661] Created
2012-03-25 12:34:29.244 exceptiontest[23661] exception raised
Note that the destructor for a never got called. This is a major concern for stack
based smartptrs such as shared_ptr and linked_ptr, as well as any STL objects that
you may want to use. Therefore it pains us to say that if you must use exceptions
in your Objective-C++ code, use C++ exceptions whenever possible. You should
never re-throw an Objective-C exception, nor are stack based C++ objects (such as
std::string, std::vector etc.) allowed in the body of any @try, @catch, or @finallyblocks.
nil ChecksUse nil checks for logic flow only.
Use nil checks for logic flow of the application, not for crash prevention. Sending a
message to a nil object is handled by the Objective-C runtime. If the method has
no return result, you're good to go. However if there is one, there may be
differences based on runtime architecture, return size, and OS X version.
Note that this is very different from checking C/C++ pointers againstNULL, whichthe runtime does not handle and will cause your application to crash. You still
need to make sure you do not dereference a NULL pointer.
BOOL PitfallsBe careful when converting general integral values to BOOL. Avoid comparing
directly with YES.
BOOL is defined as an unsigned char in Objective-C which means that it can have
values other than YES (1) and NO (0). Do not cast or convert general integral
values directly to BOOL. Common mistakes include casting or converting an
array's size, a pointer value, or the result of a bitwise logic operation to a BOOL
which, depending on the value of the last byte of the integral result, could still
result in a NO value. When converting a general integral value to a BOOL use
ternery operators to return a YES or NO value.
You can safely interchange and convertBOOL, _Bool and bool. You cannot safely
interchange BOOL and Boolean so treatBooleans as a general integral value as
discussed above. Only use BOOL in Objective C method signatures.
Using logical operators (&&, || and !) with BOOL is also valid and will return
values that can be safely converted to BOOL without the need for a ternery
operator.
-
8/2/2019 Coding Conventions Objective-C
20/23
- (BOOL)isBold {
return [self fontTraits] & NSFontBoldTrait;
}
- (BOOL)isValid {
return [self stringValue];
}
- (BOOL)isBold {
return ([self fontTraits] & NSFontBoldTrait) ? YES : NO;
}
- (BOOL)isValid {
return [self stringValue] != nil;
}
- (BOOL)isEnabled {
return [self isValid] && [self isBold];}
Also, don't directly compare BOOL variables directly with YES. Not only is it
harder to read for those well-versed in C, the first point above demonstrates that
return values may not always be what you expect.
BOOL great = [foo isGreat];
if (great == YES)
// ...be great!
BOOL great = [foo isGreat];
if (great)
// ...be great!
PropertiesProperties in general are allowed with the following caveat: properties are an
Objective-C 2.0 feature which will limit your code to running on the iPhone and
Mac OS X 10.5 (Leopard) and higher. Dot notation is allowed only for access to a
declared @property.
Naming
A property's associated instance variable's name must conform to the trailing _
requirement. The property's name should be the same as its associated instance
variable without the trailing _. The optional space between the @property and the
opening parenthesis should be omitted, as seen in the examples.
Use the @synthesize directive to rename the property correctly.
@interface MyClass : NSObject {
@privateNSString *name_;
-
8/2/2019 Coding Conventions Objective-C
21/23
}
@property(copy, nonatomic) NSString *name;
@end
@implementation MyClass
@synthesize name = name_;
@end
Location
A property's declaration must come immediately after the instance variable block
of a class interface. A property's definition must come immediately after the
@implementation block in a class definition. They are indented at the same level
as the @interface or @implementation statements that they are enclosed in.
@interface MyClass : NSObject {
@private
NSString *name_;
}
@property(copy, nonatomic) NSString *name;
@end
@implementation MyClass
@synthesize name = name_;
- (id)init {...
}
@end
Use Copy Attribute For Strings
NSString properties should always be declared with the copy attribute.
This logically follows from the requirement that setters for NSStrings always
must use copy instead ofretain.
Atomicity
Be aware of the overhead of properties. By default, all synthesized setters and
getters are atomic. This gives each set and get calls a substantial amount of
synchronization overhead. Declare your properties nonatomic unless you require
atomicity.
Dot notation
Dot notation is idiomatic style for Objective-C 2.0. It may be used when doing
simple operations to get and set a @property of an object, but should not be usedto invoke other object behavior.
-
8/2/2019 Coding Conventions Objective-C
22/23
NSString *oldName = myObject.name;
myObject.name = @"Alice";
NSArray *array = [[NSArray arrayWithObject:@"hello"] retain];
NSUInteger numberOfItems = array.count; // not a property
array.release; // not a property
Interfaces Without Instance VariablesOmit the empty set of braces on interfaces that do not declare any instance
variables.
@interface MyClass : NSObject
// Does a lot of stuff
- (void)fooBarBam;
@end
@interface MyClass : NSObject {
}
// Does a lot of stuff
- (void)fooBarBam;
@end
Automatically Synthesized Instance VariablesFor code that will run on iOS only, use of automatically synthesized instance
variables is preferred.
When synthesizing the instance variable, use @synthesize var = var_; as this
prevents accidentally calling var = blah; when self.var = blah; is intended.
// Header file
@interface Foo : NSObject
// A guy walks into a bar.
@property(nonatomic, copy) NSString *bar;
@end
// Implementation file
@interface Foo ()
@property(nonatomic, retain) NSArray *baz;
@end
@implementation Foo@synthesize bar = bar_;
-
8/2/2019 Coding Conventions Objective-C
23/23
@synthesize baz = baz_;
@end
7. Cocoa Patterns Delegate Pattern
Delegate objects should not be retained.
A class that implements the delegate pattern should:
Have an instance variable named delegate_ to reference the delegate. Thus, the accessor methods should be named delegate and setDelegate:. The delegate_ object should not be retained. Model/View/ControllerSeparate the model from the view. Separate the controller from the view and the
model. Use @protocols for callback APIs.
Separate model from view: don't build assumptions about the presentation into
the model or data source. Keep the interface between the data source and the
presentation abstract. Don't give the model knowledge of its view. (A good rule of
thumb is to ask yourself if it's possible to have multiple presentations, with
different states, on a single instance of your data source.)
Separate controller from view and model: don't put all of the "business logic" into
view-related classes; this makes the code very unusable. Make controller classesto host this code, but ensure that the controller classes don't make too many
assumptions about the presentation.
Define callback APIs with @protocol, using @optional if not all the methods are
required. (Exception: when using Objective-C 1.0, @optional isn't available, so
use a category to define an "informal protocol".)