Objective-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.
++ Objective-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.
++ 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. +
-Apple has already written a very good, and widely accepted, coding guide - for Objective-C. Google has also written a similar guide for C++. This - Objective-C guide aims to be a very natural combination of Apple's and - Google's general recommendations. So, before reading this guide, please make - sure you've read: -
+ Apple has already written a very good, and widely accepted, coding guide + for Objective-C. Google has also written a similar guide for C++. This + Objective-C guide aims to be a very natural combination of Apple's and + Google's general recommendations. So, before reading this guide, please make + sure you've read: +
Google has already released open-source code that conforms to these - guidelines as part of the Google - Toolbox for Mac project (abbreviated GTM throughout this document). + guidelines as part of the + + Google Toolbox for Mac project + + (abbreviated GTM throughout this document). Code meant to be shared across different projects is a good candidate to be included in this repository.
@@ -91,124 +103,126 @@Note that this guide is not an Objective-C tutorial. We assume that the reader is familiar with the language. If you are new to Objective-C or - need a refresher, please read The - Objective-C Programming Language. + need a refresher, please read + + The Objective-C Programming Language + .
They 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
+ An example header file, demonstrating the correct commenting and spacing
for an @interface declaration
- // GTMFoo.h
- // FooProject
- //
- // Created by Greg Miller on 6/13/08.
- // Copyright 2008 Google, Inc. All rights reserved.
- //
-
- #import <Foundation/Foundation.h>
-
- // 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 GTMFoo : NSObject {
- @private
- NSString *foo_;
- NSString *bar_;
- }
-
- // Returns an autoreleased instance of GMFoo. See -initWithString: for details
- // about the argument.
- + (id)fooWithString:(NSString *)string;
-
- // Designated initializer. |string| will be copied and assigned to |foo_|.
- - (id)initWithString:(NSString *)string;
-
- // Gets and sets the string for |foo_|.
- - (NSString *)foo;
- - (void)setFoo:(NSString *)newFoo;
-
- // Does some work on |blah| and returns YES if the work was completed
- // successfuly, and NO otherwise.
- - (BOOL)doWorkWithString:(NSString *)blah;
-
- @end
-
-
+
- An example source file, demonstating the correct commenting and spacing
+ An example source file, demonstating 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.
- //
- // GTMFoo.m
- // FooProject
- //
- // Created by Greg Miller on 6/13/08.
- // Copyright 2008 Google, Inc. All rights reserved.
- //
-
- #import "GTMFoo.h"
-
-
- @implementation GTMFoo
-
- + (id)fooWithString:(NSString *)string {
- return [[[self alloc] initWithString:string] autorelease];
- }
-
- // Must always override super's designated initializer.
- - (id)init {
- return [self initWithString:nil];
- }
-
- - (id)initWithString:(NSString *)string {
- if ((self = [super init])) {
- foo_ = [string copy];
- bar_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
+
+
+ //
+ // GTMFoo.m
+ // FooProject
+ //
+ // Created by Greg Miller on 6/13/08.
+ // Copyright 2008 Google, Inc. All rights reserved.
+ //
+
+ #import "GTMFoo.h"
+
+
+ @implementation GTMFoo
+
+ + (id)fooWithString:(NSString *)string {
+ return [[[self alloc] initWithString:string] autorelease];
}
- return self;
- }
-
- - (void)dealloc {
- [foo_ release];
- [bar_ release];
- [super dealloc];
- }
-
- - (NSString *)foo {
- return foo_;
- }
-
- - (void)setFoo:(NSString *)newFoo {
- [foo_ autorelease];
- foo_ = [newFoo copy];
- }
-
- - (BOOL)doWorkWithString:(NSString *)blah {
- // ...
- return NO;
- }
-
- @end
-
+
+ // Must always override super's designated initializer.
+ - (id)init {
+ return [self initWithString:nil];
+ }
+
+ - (id)initWithString:(NSString *)string {
+ if ((self = [super init])) {
+ foo_ = [string copy];
+ bar_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
+ }
+ return self;
+ }
+
+ - (void)dealloc {
+ [foo_ release];
+ [bar_ release];
+ [super dealloc];
+ }
+
+ - (NSString *)foo {
+ return foo_;
+ }
+
+ - (void)setFoo:(NSString *)newFoo {
+ [foo_ autorelease];
+ foo_ = [newFoo copy];
+ }
+
+ - (BOOL)doWorkWithString:(NSString *)blah {
+ // ...
+ return NO;
+ }
+
+ @end
+
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 + 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.
@@ -1123,9 +1137,177 @@ - + ++ 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 _. +
++ Use the @synthesize directive to rename the property correctly. +
+ +
+ 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.
+
+ 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 of
+ retain.
+
+ CFTypes should always have the @dynamic implementation
+ directive.
+
+ Since CFTypes can't have the retain property
+ attribute, the developer must handle retaining and releasing the
+ value themselves. In the rare case that you do actually want
+ assignment it is better to make that completely clear by actually
+ implementing the setter and getter and commenting why that is the
+ case.
+
+ Use implementation directives for all properties even if they are
+ @dynamic by default.
+
+ Even though @dynamic is default, explicitly list it out
+ with all of the other property implementation directives making it
+ clear how every property in a class is handled at a single glance.
+
+ 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.
+
+ We do not allow the use of dot notation to access properties for + the following reasons: +
+[foo setBar:1] it is immediately clear that you are
+ working with an Objective-C object. When one sees
+ foo.bar = 1 it is not clear if foo is an object, or
+ a struct/union/C++ class.
+