<p> When writing pure Objective-C code, we mostly follow standard <ahref="http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html">Objective-C
naming rules</a>. These naming guidelines may differ
Class names (along with category and protocol names) should start as
uppercase and use mixed case to delimit words.
</SUMMARY>
<BODY>
<p>
In <em>application-level</em> code, 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. <code>GTMSendMessage</code>).
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Category Names">
<SUMMARY>
Category 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.
</SUMMARY>
<BODY>
<p>
For example, if we want to create a category on <code>NSString</code>
for parsing, we would put the category in a file named
<code>GTMNSString+Parsing.h</code>, and the category itself would be
named <code>GTMStringParsingAdditions</code> (yes, we know the file
name and the category name do not match, but this file could have many
separate categories related to parsing). Methods in that category
should share the prefix (<code>gtm_myCategoryMethodOnAString:</code>)
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.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Objective-C Method Names">
<SUMMARY>
Method names should start as lowercase and then use mixed case.
Each named parameter should also start as lowercase.
</SUMMARY>
<BODY>
<p>
The method name should read like a sentence if possible, meaning you
should choose parameter names that flow with the method name. (e.g.
<code>convertPoint:fromRect:</code> or
<code>replaceCharactersInRange:withString:</code>). See <ahref="http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF">Apple's
Guide to Naming Methods</a> for more details.
</p>
<p>
Accessor methods should be named the same as the variable they're
"getting", but they should <em>not</em> be prefixed with the word
"get". For example:
<BAD_CODE_SNIPPET>
- (id)getDelegate; // AVOID
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
- (id)delegate; // GOOD
</CODE_SNIPPET>
</p>
<p>
This is for Objective-C methods only. C++ method names and functions
continue to follow the rules set in the C++ style guide.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Variable Names">
<SUMMARY>
Variables names start with a lowercase and use mixed case to delimit
words. Class member variables have trailing underscores. For example:
<var>myLocalVariable</var>, <var>myInstanceVariable_</var>. Members
used for KVO/KVC bindings may begin with a leading underscore
<i>iff</i> use of Objective-C 2.0's <code>@property</code> isn't
allowed.
</SUMMARY>
<BODY>
<SUBSECTIONtitle="Common Variable Names">
<p>
Do <em>not</em> use Hungarian notation for syntactic attributes,
such as the static type of a variable (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:
</p>
<BAD_CODE_SNIPPET>
int w;
int nerr;
int nCompConns;
tix = [[NSMutableArray alloc] init];
obj = [someObject object];
p = [network port];
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
int numErrors;
int numCompletedConnections;
tickets = [[NSMutableArray alloc] init];
userInfo = [someObject object];
port = [network port];
</CODE_SNIPPET>
</SUBSECTION>
<SUBSECTIONtitle="Instance Variables">
<p>
Instance variables are mixed case and should be suffixed with a
trailing underscore, e.g. <var>usernameTextField_</var>. However,
we permit an exception when 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, <code>@property</code> and
<code>@synthesize</code> provide a solution that conforms to the
naming guidelines.
</p>
</SUBSECTION>
<SUBSECTIONtitle="Constants">
<p>
Constant names (#defines, enums, const local variables, etc.) should
start with a lowercase <var>k</var> and then use mixed case to
delimit words, i.e. <var>kInvalidHandle</var>,
<var>kWritePerm</var>.
</p>
</SUBSECTION>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORYtitle="Comments">
<p>
Though a pain to write, they are absolutely vital to keeping our code
readable. The following rules describe what you should comment and where.
But remember: while comments are very important, the best code is
self-documenting. Giving sensible names to types and variables is much
better than using obscure names and then trying to explain them through
comments.
</p>
<p>
When writing your comments, write for your audience: the next
contributor
who will need to understand your code. Be generous — the next
one may be you!
</p>
<p>
Remember that all of the rules and conventions listed in the C++ Style
Guide are in effect here, with a few additional points, below.
</p>
<STYLEPOINTtitle="File Comments">
<SUMMARY>
Start each file with a copyright notice, followed by a
description of the contents of the file.
</SUMMARY>
<BODY>
<SUBSECTIONtitle="Legal Notice and Author Line">
<p>
Every file should contain the following items, in order:
<ul>
<li>a copyright statement (for example,
<code>Copyright 2008 Google Inc.</code>)</li>
<li>a license boilerplate. Choose the appropriate boilerplate
for the license used by the project (for example,
Apache 2.0, BSD, LGPL, GPL)</li>
</ul>
</p>
<p>
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.
</p>
</SUBSECTION>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Declaration Comments">
<SUMMARY>
Every interface, category, and protocol declaration should have an
accompanying comment describing its purpose and how it fits into the
larger picture.
</SUMMARY>
<BODY>
<CODE_SNIPPET>
// A delegate for NSApplication to handle notifications about app
// launch and shutdown. Owned by the main app controller.
@interface MyAppDelegate : NSObject {
...
}
@end
</CODE_SNIPPET>
<p>
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.
</p>
<p>
Additionally, each method in the public interface should have a
comment explaining its function, arguments, return value, and any
side effects.
</p>
<p>
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.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Implementation Comments">
<SUMMARY>
Use vertical bars to quote variable names and symbols in comments rather
than quotes or naming the symbol inline.
</SUMMARY>
<BODY>
<p>
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":
</p>
<CODE_SNIPPET>
// Sometimes we need |count| to be less than zero.
</CODE_SNIPPET>
<p>
or when quoting something which already contains quotes
</p>
<CODE_SNIPPET>
// Remember to call |StringWithoutSpaces("foo bar baz")|
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINTtitle="Object Ownership">
<SUMMARY>
Make the pointer ownership model as explicit as possible when it falls
outside the most common Objective-C usage idioms.
</SUMMARY>
<BODY>
<p>
Instance variable pointers to objects derived from NSObject are
presumed to be retained, and should be documented as <b>weak</b> if
they are not retained by the class. However, instance variables which
are labeled as IBOutlets are presumed to not be retained by the class,
and should be documented as <b>strong</b> if the class does retain
them.
</p>
<p>
Where instance variables are pointers to CoreFoundation, C++, and
other non-Objective-C objects, they should always be documented in
comments as strong or weak. Be mindful that support for automatic C++
objects encapsulated in Objective-C objects is disabled by default, as
described <ahref="http://chanson.livejournal.com/154253.html">here</a>.
</p>
<p>
Examples of strong and weak documentation:
<CODE_SNIPPET>
@interface MyDelegate : NSObject {
@private
IBOutlet* okButton_; // normal NSControl
IBOutlet* myContextMenu_; // manually-loaded menu (strong)
AnObjcObject* doohickey_; // my doohickey
MyController* controller_; // so we can send msgs back (weak, owns me)
// non-NSObject pointers...
CWackyCPPClass* wacky_; // some cross-platform object (strong)
CFDictionaryRef* dict_; // (strong)
}
@end
</CODE_SNIPPET>
<dl>
<dt>strong</dt><dd>The object will be <code>retain</code>'d by this class</dd>
<dt>weak</dt><dd>The object will be <b>not</b> be <code>retain</code>'d by this class
(e.g. a delegate).</dd>
</dl>
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORYtitle="Cocoa and Objective-C Features">
<STYLEPOINTtitle="Member Variables Should Be @private">
<SUMMARY>
Member variables should be declared <code>@private</code>.
version (see <ahref="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_2_section_3.html#//apple_ref/doc/uid/TP30001163-CH11-SW7">Apple's
