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:

C1

Use 4 spaces for indentation, no tabs.

C2

Opening braces go on the same line as the declaration. This is for both function declarations and control flow statements (if, for, etc.).

C3

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.

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.
:param: min The lower bound
:param: 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.