# Zarra Studios Coding Style Guide

## Why Do We Need A Style Guide

We have come to that point in the company’s life that I can no longer review every single line of code before it is passed either to a customer or put directly into production. However, there is always going to be the situation where I need to dive into a piece of code to get an issue sorted out; even if it is just another set of eyes on the problem.

## Baseline

The baseline for this style guide is that any team of developers should be working from a single play book when it comes to the code style used. This makes the code more maintainable and easier to consume.

Since my company cannot fire me (trust me I have tried; several times) nor can they promote me to being a manager (also tried several times), I am the one “constant” and therefore the style guide that we will be using is based on my personal preferences. Putting it into a written form makes it easier to keep everything consistent and gives me something to point to :)

At the end of the day, I am responsible for every line of code being written by the company. I need to be able to stand behind it and when necessary, answer for it. Therefore all of this boils down to one simple statement:

**My Code, My Rules.**

## Dot Notation

Lets get the big one out of the way. Dot syntax is not to be used on any projects that Zarra Studios produces with a singular exception:

CALayer *layer = [CALayer layer];
layer.contents = someCGImageRef;

## Casting

Objective-C is a dynamic language and casting generally indicates you are probably doing something wrong or at least lying to the compiler. Therefore casting is to be avoided in every situation possible and every use of casting should be defendable with something other than “it made the warning go away”. If in doubt, use `id`. Accessing the toll-free bridging is one of the few exceptions. If anyone knows of a way to do toll-free bridging without casting, please let me know.

## Spacing

Code is to be indented 2 spaces and no tabs. If you want to wrap a long line of code then make sure it is colon aligned per Xcode’s formatting. However I prefer if you did not wrap the lines. Xcode formats them rather nicely.

Keywords such as if, while, do, switch, etc. should have a space after them.

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. Code should be indented 2 spaces from the opening bracket.

When brackets are needed in a switch they are to be left aligned with the case line and on their own line. NOTE: brackets in switches should be avoided.

All other brackets should inline.

## Method signatures

Method signatures should be left aligned. There should be a space after the scope (the plus or the minus sign). There should be a space between the method segments. Other than that there should be no spaces in the method signature. For example:

– (void)setExample:(NSString *)text;

Is incorrect as it should be written:

– (void)setExample:(NSString*)text;

## Booleans

Objective-C uses `YES` and `NO`. Therefore `true` and `false` are incorrect. Also since `nil` resolves to `NO` it is unnecessary to compare it in conditions. For example:

if (someObject == nil) …

Is redundant and should be written as:

if (!someObject) …

Likewise, if a method call returns a `BOOL` then checking it against a `BOOL` is redundant.

if ([someObject boolValue] == NO) …

is incorrect and should be written:

if (![someObject boolValue]) …

## Variable names

Variable names should be descriptive of what they represent. Single letter variable name should never be used, even for incrementers. If it is an index, call it index.

## Empty methods

Any method that is empty or just calls `super` should be removed from the source code as they are redundant.

## Comments

Comments should be rare. Code is easier to read than comments. Comments go stale, code doesn’t. The only comments should be along the lines of:

/* We are doing this in a strange way because the normal solution resulted in …
* Therefore this solution is the correct one.
*/

If the code is self explanatory (as it should be with descriptive variable names and methods) then comments are not necessary.

## dealloc

`-dealloc` is important and should be placed directly below the `-init` methods of any class. If there are no `-init` methods then it should be the first method after class level methods.

## @synthesize and @dynamic

Both @synthesize and @dynamic are boiler-plate code. They should be put at the top of the class just below the @implementation. Each @synthesize and @dynamic should be on a single line.

## @property

Property definitions should be used in place of iVars. As of Xcode 3.2.5, we should no longer be declaring iVars *at all*. This will help to insure proper memory management. In addition, direct iVar access should be avoided except during initialization of the variable and in the `-viewDidUnload` and `-dealloc` methods.

## ZAssert

ZAssert should be used in place of NSAssert and should be used whenever a critical check is required.

## DLog

DLog should be used in place of NSLog in all situations. NSLog should not be used directly in the code.

## ALog

Whenever a situation occurs that “shouldn’t” then an `ALog` should be used so that those situations can be captured via assertions or logs.

## Protocols

Protocol implementations should be separated out by `#pragma` marks.

## Prefix.pch

The pre-compiled header should always be named `Prefix.pch` and not `Project_Prefix.pch` or anything else.

## Info.plist

The info.plist should always be named `Info.plist` and not `Project_Info.plist` or anything else.

## App Delegate

The application delegate, if its a separate class, should be named `AppDelegate` and not `Project_AppDelegate` or anything else.

## xib files

xib files should always be saved in their language specific folders. The default folder for English is `en.lproj`.

xib file names should end in view, menu or window and never in “controller”.

## Class files

All class files should be stored in the Classes directory unless they belong to another subproject or library. The only files that should be in the root of the project are: Prefix.pch, Info.plist and main.m.

## Frameworks

Framework imports should be in the `Prefix.pch` and not in the individual class files. Any existing framework imports in the class implementations or headers should be removed.

## Releasing

Whenever an object is released, the pointer should also be set to nil. These two calls should be on the same line:

[object release], object = nil;

## Code width

Code should not be set to an arbitrary width. We have wide monitors and an editor that smart wraps the code. Do not limit code to 80 columns or any other arbitrary width unless it is to be printed.

## 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.

## String constants

String constants should be `#define` and stored in the `Prefix.pch`. The exception is a `#define` that is highly local to a specific class.

## 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.

## Conclusion

This document is a living document and will be updated as I run across other things that are not clearly spelled out. I do not take these to be unreasonable although they are hopefully clear and as complete as possible.

While I am always happy to debate these rules, here is not the place. Find me in a tavern and a conference and we can talk all night.

Comments are disabled as this is not a place for debate on this subject.