My Coding Style
Jul 29, 2011
My Code, My Rules.
This style guide is heavily influenced by the "Zarra Studios Coding Style Guide" [1], and whilst we agree on lots of things, there are major differences.
Spacing
- Use only spaces, and indent 2 spaces at a time.
- Keywords such as if, while, do, switch, etc. should not have a space after them.
- One space should be used between - or + and the method return type.
- Avoid wrapping lines - XCode does a good job at displaying long lines.
- Wasted vertical space should be avoided. There should be only one empty line between methods.
Brackets
- Method brackets should be on the following line and flush left (this might seem a waste of vertical space).
- Code should be indented 2 spaces from the opening bracket.
- Brackets in switches should be avoided but when needed they are to be left aligned with the case line and on their
own line.
- All other brackets should be inline.
Naming conventions and locations
- Class names should follow the Pascal Case convention: should start as uppercase and use mixed
case to delimit words.
- File names should reflect the name of the class implementation that they contain - including
case.
- Variable and method names should follow the Camel Case convention: start as lowercase and then
use mixed case. Each parameter should also follow this convention.
Use descriptive names, the longer the better. Don't use single letter variables - the only exception is i used for
incrementers.
- For constant names use all caps with underscores between words.
- Plural denotes a collection.
- The pre-compiled header should always be named Prefix.pch and not Project_Prefix.pch or
anything else. The only exception is when multiple targets are present and each target requires its own header- it
should be named Prefix.pch
- The info.plist should always be named Info.plist and not Project_Info.plist or anything else.
The only exception is when multiple targets are present and the info.plist file should be named Target-Info.plist
- The application delegate, if its a separate class, should be named AppDelegate and not
Project_AppDelegate or anything else.
- xib file names should end in view, menu or window and never in "controller".
- Framework imports should be in the Prefix.pch and not in the individual class files.
- String constants should be #define and stored in the Prefix.pch. The exception is a #define that
is highly local to a specific class.
- Protocol implementations should be separated out by #pragma marks.
Memory Management
Method signatures
File locations
- All class files should be stored in the Classes directory unless they belong to another subproject or library
- Classes should be stored in subfolders based on their purpose or section of the app i.e. assign a folder to a
group in XCode.
- The only files that should be in the root of the project are: Prefix.pch, Info.plist, main.m, Default.png and
icon.png (and their variants).
Booleans
Boolean can only have 2 values: YES and NO. True and false are incorrect.
Comments
There is no such thing as too many comments. Comments are desirable but not required as the code should be
self-explanatory.
Avoid casting
This generally indicates you are probably doing something wrong and trying to lie to the compiler. Use id as the last
resort.
Libraries / submodules
Each library should contain a main .f file, named LibraryName.h, that includes all relevant headers of the classes
defined/extended. It should also contain any settings, default values, etc.
Debugging
- ZAssert should be used in place of NSAssert and should be used whenever a critical check is required.
- DLog should be used in place of NSLog in all situations. NSLog should not be used directly in the code.
- Whenever a situation occurs that "shouldn't" then an ALog should be used so that those situations can be captured
via assertions or logs.
Golden Path
When coding with conditionals, the left hand margin of the code should be the "golden" or "happy" path. We should
never see:
- (void)someMethod
{
if ([someOther boolValue]) {
//Do something important
}
}
That is difficult to read. Instead the code should fail early and fail often:
- (void)someMethod
{
if (![someOther boolValue]) return;
//Do something important
}
Likewise, a method should not be bisected with a conditional as follows:
- (void)someMethod
{
if ([someOther boolValue]) {
//Do something important
} else {
//Do something else important
}
}
This is also hard to read and should be re-written as:
- (void)someMethod
{
if ([someOther boolValue]) {
//Do something important
return;
}
//Do something else important
}
There is one situation where a bisection of the code is acceptable:
- (void)someMethod
{
if ([someOther boolValue]) {
//Do something important
} else {
//Do something else important
}
//Do this no matter what
}
The goal here is to make the code on the left margin to be the "expected" code execution path and the code that is
indented to be the exception. Consistency in this area is important to code readability.
No Exception ;)
Throwing exceptions should be avoided - these are to be used for truly exceptional scenarios and not for controlling
logic flow.
Boyscout
Whenever you are in a piece of code it should be left cleaner than when you found it if possible. If you find code
that violates this guide, correct it. If the code is out dated then update it.
Version control
- Use version control!!!
- git is the preferred choice.
- don't commit code that generated warnings!!!
- run all unit tests before committing. Make sure they all pass.
Other things to consider
- Keep the code simple.
- Like all premature things, premature optimisation is bad.
- Don't overdesign.
- Don't underdesign.
- Avoid bugs.
- Be consistent.
- Use common sense.
References:
This is a live document that is going to evolve over time. Feel free to get in touch with suggestions, etc. Thank
you!