Code Standards

These are the coding standards for Traq 3.x

If you're wanting to contribute to Traq and want the code you write to be included into the project, please try to follow the standards on this page.

File encoding, line endings and indentations

All files should be UTF8 without the rubbish (BOM), using the Unix line endings and line indentations should be done with four spaces, not tabs.

Line comments

Comments should be formated like so:

// Let's make sure the user has permission to view the project page.
if (current_user()->permission('view', $project_id))

That's two slashes, obviously, with a space then the first word capitalised, if the comment is going to be much longer than the line itself, use multiple lines like so:

// Check that the project variable, if it is, fetch the project.
// We do this because sometimes the project variable is passed to
// the function.
if ($project !== null)

Classes

Classes should be named with the CamelCase style, for example UsersController, MyClass, and so on.

All classes should have their own comment block with a small description of what it does, what package or sub-package it belongs to, the authors name and the first version it was added in, the opening and closing brackets should be on their own line, here is an example:

/**
 * Handles all the user-based pages.
 *
 * @subpackage Controllers
 * @author John Smith <john@smith.name>
 * @since 0.1
 */
class UsersController extends AppController
{
    ....
}

Class Functions

Class functions should be named in under_score format: get_data, my_function and so on.

When creating a function inside a class, only include the @since information if the function being created is added in a different version than the class.

Please also read the standalone functions section for a complete list of information functions should have in the comments.

Functions

Standalone functions should be named in under_score format: get_data(), my_function() and so on.

Functions should be treated the same as classes, but also include the main package and sub-package if applicable, also include the parameters information and the data type that is returned (string, array, boolean, etc), for example:

/**
 * Processes the data passed to it and escapes any HTML.
 *
 * @package Traq
 * @subpackage Helpers
 * @author John Smith <john@smith.name>
 * @since 0.1
 *
 * @param string $data The data array to be processed.
 *
 * @return string
 */
function escape_html($data)
{
    ....
    return $data;
}

Variables

Variables are to use the same naming convention as standalone functions, which is under_score: my_variable, my_other_variable.

However, if you're inside a class and using a mixture of public, private and/or protected variables, add an underscore (_) to the private and protected variables, for example: _unescaped_html.

Conditionals, Loops, etc

Conditionals, loops and similar should be formatted like so:

if ($something === true) {
    ....
}

foreach ($people as $person) {
    ....
}