Coding Standards

Coding Standards

This document describes the guidelines and specifications for the C4 code base. Anything that doesn't follow these guidelines will be rejected. Please read this carefully before contributing.

Code style

The basic rule is "follow the current style". We want the code follow the same formatting style throughout. In particular:

CS1

Use 4 spaces for indentation, no tabs. Be sure to set this preference in Xcode.

CS2

Opening braces go on the same line as the declaration. This is for both function declarations and control flow statements (if, for, etc.). Closing braces go on their own line except when followed by an else.

CS3

Remove Xcode-generated comments and any comments that don't add value to the code. In particular remove the default Copyright statement generated by Xcode templates.

CS4

Use descriptive names with camel case. Class names should be capitalized, while method names and variables should start with a lower case letter.

CS5

There should be exactly one blank line between methods.

CS6

There should be no space between a variable name and its type or between a function parameter name and it's type. Do var color: Color not var color : Color.

Access Control

AC1

Use private sparingly. By default things are internal, so unless it's something that needs to be public just skip the access specifier. Use private only if the variable or function is an implementation detail.

AC2

Put the access control specifier first. For instance public final class A instead of final public class A.

AC3

Put public first. For instance public internal(set) var a instead of internal(set) public var a.

Optionals

OP1

Avoid force-unwrapping of optionals. Never use ! unless you are completely certain that the optional will never be nil. Instead use if let and guard

OP2

Prefer guard over if let and always provide a reason for failure:

guard let v = variable else {
    print("reason for failure")
    return
}
v.doSomething()

Closures

CL1

Write closures without spaces around the ->. For instance ()->() instead of () -> ().

CL2

Use () instead of Void. For instance ()->() instead of Void->Void.

CL3

Call them actions, not closures. For instance delay(time: Double, action: ()->()).

##Initializers

######I1 Avoid creating multiple initializer by setting values for initializer variables:

init(someVar, anotherVar = 0.0, yetAnotherVar = "something")

Instead of:

init(someVar) {
    init(someVar, anotherVar: 0.0)
}

init(someVar, anotherVar: Double) {
    init(someVar, anotherVar: 0.0, yetAnotherVar: "aString")
}

init(someVar, anotherVar: Double, yetAnotherVar : String) {
    //actual init method
}

Documentation

C4 is a library meant to make life easier for developers. As such we strive to have comprehensive documentation. Document everything that is public.

D1

Every public class, struct or function needs to have a documentation block preceding it. The block needs to be formatted using Xcode auto-documentation format. For instance:

/**
  Return a random integer greater than or equal to min and less than max.
  - parameter min: The lower bound
  - parameter max: The upper bound
  - returns: A random value greater than or equal to min and less than max.
*/
public func random(min: Int, max: Int) -> Int 

D2

Add code comments only to explain the why of the code, not the what or the how. In other words explain the reasoning behind the code, not what it does. If the code's intent is not clear then rewrite it in a way that is. For instance avoid writing

// Adds a and b and puts the result in c
let c = a + b

Instead write

// We need to store this result because we need it later to compute x
let c = a + b

Testing

We are not aiming for 100% test coverage. Writing tests for default constructors and trivial functions is a waste of resources. Instead aim for writing tests where they matter the most.

T1

Always write unit tests for non-trivial code and code where there is a possibility of having edge-case problems.