Dev:Coding Standards

From Habari Project

Jump to: navigation, search

Contents

Abstract

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.


Inspiration

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.


Standards

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.

Aside

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


Indenting

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

Aside

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

Quotes

Use single quotes unless double quotes are warranted.

Naming Conventions

Variables

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

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';


Classes

Class names should use CamelCase with no separation between words.

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

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

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

if ( condition1 || condition2 ) {
	action1;
}
elseif ( condition3 && condition4 ) {
	action2;
}
else {
	otheraction;
}

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

switch ( statement or expression ) {
  case 0:
    // Do stuff here
    break;
  case 1:
    // Do stuff here
    break;
  default:
    // Do stuff here
    break;
}

Function Calls

Incomplete!


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

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(
	'hello',
	'world',
	'foo' => 'bar',
	'second_level' => array(
		'foo' => 'bar'
	),
);
Aside

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(
	'hello',
	'world',
	'foo' => 'bar',
);
Aside

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

Comments

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

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.


Single-line

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

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


Multi-line

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.

'/[a-z]+_/';
'#<p>.*</p>#';

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 );

References

  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