Code Quality & Formatting Guide

Written by @the-killer-rabbit. He deserves ice cream.

##Conditional Statements

If, elseif, and else should be on the same line as their opening brace, and there should be one newline after the previous closing brace. Example:

if ($age == 42) {
    ...
}
elseif ($age == 0) {
    ...
}
else {
    ...
}

##Switch Statements

In switch statements, case and default should not be indented, but the content of the cases should, like so:

switch ($age) {
case 0:
    // Do stuff.
    break;
case 42:
    // Do stuff.
    break;
default:
     // PANIC.
}

##Functions/Methods

Your braces should be aligned with one space after the parenthesis, then a brace on the same line.

These are not acceptable:

function getFilename()
{
    return $this->filename;
}

function getFilename()
    {
    return $this->filename;
    }

This is acceptable:

function getFilename() {
    return $this->filename;
}

##Strings

Strings can be enclosed in single or double quotes. Strings in double quotes are parsed by PHP, so you can put variables within them like this:

$name = 'John Doe';
echo "I am {$name}";

Concatenation can done via the . operator.

$string = 'Hello there, ' . $name;

Use sprintf to concatenate strings when you need to concatenate three or more variables:

$string = sprintf("User %s is %s years old on %s!", $user, $age, $date);

##Classes

Classes should be set up like this:

1. Variables
2. [Blank Line]
3. Constants
4. [Blank Line]
5. Methods

Built in type variables should be initialized when declared. Class variables (ones with a constructor) should be initialized in the constructor.

Here is an example of a good class:

class Car {
    $make = "";
    $radio = null;

    const WHEELS = 4;

    function __construct($make) {
        $this->make = $make;
        $this->radio = new Radio();
    }
}

The functions should be organized in this order:

1. Constructor
2. Destructor
3. Getters/setters (e.g. each get/set paired, in order of variable declaration)
4. Procedures
5. Functions.

Controllers

Controller classes must extend CI_Controller.

Models

Model classes must extend CI_Model.

Libraries

Libraries don't have to extend any class.

##Whitespace

Code should be indented with 4 spaces (not tabs). You should be able to configure the tab key to input 4 spaces in your editor of choice. This is incorrect:

function getFilename() {
return $this->filename;
}

This is correct:

function getFilename() {
    return $this->filename;
}

There should be no space between parenthesis and parameters. For example, this is not acceptable:

function setFilename( $filename ) {

This is acceptable:

function setFilename($filename) {

Every comma , should have a space immediately after it. This is not acceptable:

function pow($number,$power) {

This is acceptable:

function pow($number, $power) {

#Naming Conventions

##Classes

The first letter of class names should be capitalized. Use underscores to separate words within the name. (Example: Class_name.) Class filenames must be the same as the class.

##Functions & Methods

Function/method names should be lowercase. Use underscores to separate words within the name.

Example function name: set_filename

Function/method names should be descriptive and concise. Setters and getters should always begin with set and get, respectively.

##Variables

Like functions, variable names should be lowercase and use underscores to dvidie words. They should also be descriptive and concise.

These are not acceptable:

$x = 42;
$something = "Hello world!";
$u = 12;

But these are:

$average = 42;
$greeting = "Hello world!";
$user_id = 12;

Constants should be defined in all caps.

Use the define function to define a constant:

define('GREETING', 'Hello World!');

Use the const operator to define class constants:

const MODULE_PATH = "./modules";

#Commenting

##Single line comments

These should be used for explaining how parts of code work. The comment should be written in as few words as possible, while still containing all pertinent information. There should be a single space before and after the two slashes.

Example 1

$quotient = $div1 >> 2; // Using bitwise shift as it is faster than the division.

Example 2

public function load_all() {
    $id = $this->input->get('id');
    // Get comments on this post (null = no limit)
    $comments = $this->comments_model->get_all($id, null);
    // Load comments HTML
    $html = $this->comments_model->comment_html($comments, true);
    // Output JSON
    json_output(array('html' => $html), true);
}

##Multi line comments

Every function, method, and class should have a comment using phpDoc syntax.

Example:

/**
 * Returns the current filename.
 *
 * @param bool $fullpath Pass `true` for the full path, pass `false` to just get the filename.
 * @returns string
 * @throws Exception
 *
 */
function getFilename($fullpath = false) {
    if ($this->filename == "") {
        throw Exception("File not found.");
        return null;
    }
    else {
        return $this->filename;
    }
}