Dev:Coding Standards

From Habari Project

Jump to: navigation, search



The purpose of this document is to provide a standard set of coding standards and guidelines by which all Habari contributors will abide. By establishing a standardized coding style we provide an easier and more straight-forward entry path for new contributors and reduce the learning curve required for developers to comprehend existing code.


Many sources have been used during the compilation of this document. All major sources of inspiration should be cited.

As these sources provide the primary basis for this document, inconsistencies are noted as appropriate.


PHP Tags

Always use the full tags to delimit PHP code:

<?php ?>

Do not use the shorthand format:

<? ?>

Always include a closing PHP tag at the end of code files.


This differs from the Drupal [2] and Zend [3] standards, both of which omit the closing tag.


Use tabs for indentation, not spaces. No trailing whitespace.


This differs from the Drupal [2], PEAR [4], and Zend [5] standards, all of which use spaces instead of tabs.


Use single quotes unless double quotes are warranted.

Naming Conventions


Variables, whether global or class / local scope, should be all-lowercase with words separated by underscores. Do not use camelCaseNames.

$some_variable = 'foo';
$another_variable = array( 'bar' );


Constants, whether global or class scope, should be all-uppercase with words separated by underscores.

// global constants
define( 'DEBUG', true );
define( 'CACHE_CLASS', 'FileCache' );
// class constants
const DB_VERSION = 1845;
const HABARI_VERSION = '0.5-alpha';


Class names should use CamelCase with no separation between words.

class Version { ... }
class DatabaseConnection { ... }
class UserThemeHandler extends ActionHandler { ... }

This differs from the Drupal [2] standards, which use "studlyCaps" for class names, and the PEAR [6] and Zend [7] standards, which use underscores between words.


Functions, whether global or class scope, should follow the same naming standard as variables.

// global
function _t( $text, $domain = 'habari' ) { ... }
// class
public function get_results( $query, $args = array() ) { ... }
private function add_error( $error ) { ... }
protected function load_tables( ) { ... }

Control Structures

Control structures include if, for, while, switch, etc. Control statements should have one space between the control keyword and opening parenthesis, and spaces around conditions.

Comparison Order

When comparing a variable to a set value, always include the variable first and the value expected second. Logically you are comparing a thing (the variable) to a possible value, not the other way around.

This convention maintains the order you would logically expect each piece to occur in an English sentence if you were reading or explaining the code.

// good!
if ( $foo == 'bar' ) {
if ( $post->id == 0 ) {
// bad!
if ( 'bar' == $foo ) {
if ( 0 == $post->id ) {


if ( condition1 || condition2 ) {
elseif ( condition3 && condition4 ) {
else {

Else statements should be placed on their own line, not on the same line as the preceding closing curly brace. The omission of curly braces for single-line conditions is highly discouraged.


switch ( statement or expression ) {
  case 0:
    // Do stuff here
  case 1:
    // Do stuff here
    // Do stuff here

Function Calls


Function Declarations

Functions (regardless of scope) should be declared using the following format:

public static function foo ( $bar = '' )

The opening and closing braces should be on their own line.

Note that [public|private|protected] should always come first in the function declaration (if declaring a class method). The static declaration is secondary.


Arrays should be formatted with a space separating each element and assignment operator.

$some_array = array( 'hello', 'world', 'foo' => 'bar' );

Longer array declarations should be wrapped to multiple lines, one element per line, and indented one level.

$some_long_array = array(
	'foo' => 'bar',
	'second_level' => array(
		'foo' => 'bar'

This differs from the Zend [8] standards, which advocate insanity.

Trailing Comma

Note the comma at the end of the last array element. While optional, this usage is encouraged on longer arrays and those where new elements may be added regularly. It helps to prevent the accidental omission of a new comma when array elements are added to the end of the array and is ignored by the PHP interpreter.

$some_long_array = array(
	'foo' => 'bar',

This differs from the Drupal [2] standards, which advocate the regular use of a trailing comma.


Inline Documentation

Inline documentation of source files should follow the PHPDoc formatting conventions [9] .

PHPDoc standards allow for the name of the @param variable to be optionally specified, but the Habari standards require the variable name.

 * get_dir returns a complete filesystem path to the requested item
 *	'config_file' returns the complete path to the config.php file, including the filename
 *	'config' returns the path of the directory containing config.php
 *	'user' returns the path of the user directory
 *	'theme' returns the path of the site's active theme
 * @param string $name the name of the path item to return
 * @param bool $trail whether to include a trailing slash.  Default: No
 * @return string Path
public static function get_dir( $name, $trail = false ) { ... }


Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

Note that Perl / shell style comments (#) are discouraged in any scenario.


Comments spanning a single line should utilize standard C++ comments.

// does the cache have our list already?
if ( Cache::has( 'some_list' ) ) { ... }


Comments which span multiple lines should utilize C-style comments.

 * Monthly Archives Plugin
 * Usage: <?php $theme->monthly_archives(); ?>
class MonthlyArchives extends Plugin { ... }

Boolean Values and Null

Boolean values, and null should be referenced by name and in all lowercase letters.

$value = TRUE;   // bad!
$value = 1;      // bad!
$value = NULL;   // bad
$value = true;   // good!
$value = false;  // good!
$value = null;   // good!

Database access

Calls through the DB class should use the brace syntax for table names.

DB::query( 'SELECT * FROM {table}' );

Including Code

When including code stored in external files, the include_once and require_once statements are preferred (over simply include and require), as they prevent possible duplicate calls. While these are statements and not functions, parenthesis should be used.

include_once( 'some_conditionally_required_file.php' );
require_once( 'some_unconditionally_required_file.php' );

Regular Expressions

All regular expressions should be delimited by /, unless they contain /, in which case use #. Always use ', otherwise you have to double-backslash everything.


Dynamic Variables / extract()

Use of either dynamically-named variables or the extract function are highly discouraged. Both methods obfuscate the source of variables and can result in unexpectedly-overwritten values. When extracting the values of handler_vars, they could also result in unexpected XSS vulnerabilities, as this includes the $_GET and $_POST arrays.

// dynamic variable
$var = 'foo';
$$var = 'bar';
// extract
$array = array( 'foo' => 'bar' );
extract( $array );


  1. Note that the Drupal Coding Standards are heavily based on the PEAR standards.
  2. 2.0 2.1 2.2 2.3 See Drupal Coding Standards
  3. Zend: File Formatting - General
  4. PEAR: Indenting
  5. Zend: Indentation
  6. PEAR: Naming Conventions - Classes
  7. Zend: Naming Conventions - Classes
  8. Zend: Arrays
  9. PHPDoc Manual
Personal tools