Skip to content

Coding Standards

Jump to bottom
Engelbert edited this page Jan 8, 2015 · 1 revision

Note: The ProjectPier Coding Standards applies to code that is to become a part of ProjectPier. This document is based on the Drupal and PEAR Coding standards.

File Format

All source code files should be formatted with Unix line endings ( the \n and not the \r\n that many Windows editors use). This is important also for translations. It is also our policy not to include names in the source files - Acknowledgements are provided in other avenues - the issue tracker, changelog, and maintainers files.

Indenting

Use an indent of 2 spaces, with no tabs.

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

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

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

switch (condition) {
  case 1:
    action1;
    break;
  case 2:
    action2;
    break;

  default:
    defaultaction;
    break;
}

Note: It is sometimes acceptable to add a comment at the end of any very long sections of bracketed/braced (sp?) code to assist in readability and clarity.

Functions

Function Calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here’s an example:

$var = foo($bar, $baz, $quux);

As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

$short         = foo($bar);
$long_variable = foo($baz);
$long_variable = foo($baz);

Function Declarations

function array_var($from, $name, $default = null) {
  if (is_array($from)) {
    return isset($from[$name]) ? $from[$name] : $default;
  }
  return $default;
}

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.

Arrays

Arrays should be formatted with a space separating each element and assignment operator, if applicable:

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

Note that if the line spans longer than 80 characters (often the case with form and menu declarations), each element should be broken into its own line, and indented one level:

$form['title'] = array(
  '#type' => 'textfield',
  '#title' => 'Title',
  '#size' => 60,
  '#maxlength' => 128,
  '#description' => 'The title.',
);

Note the comma at the end of the last array element—this is not a typo! It helps prevent parsing errors if another element is placed at the end of the list later.

Comments

Inline documentation for classes should follow the phpDocumentor convention. More information about phpDocumentor can be found here:

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. Another general rule rule: if you need to write a lot to describe what certain code block is doing extract it to a function or method and properly name it then instead of writing a long comment, put it in the phpDocumentor syntax.

Note: This is the documentation syntax that activeCollab supposedly uses (I haven't checked how pervasive it is) but I'm open to using Doxygen if that is preferred

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Including Code

Don’t forget that PHP5 supports auto loading of classes and that you don’t need to manually require all of the classes. Require only classes inside of factory methods or classes that are used all the time (requiring a class manually is still much faster than autoload process).

Anywhere you are unconditionally including a class file, use require_once(). Anywhere you are conditionally including a class file (for example, factory methods), use include_once(). Either of these will ensure that class files are included only once. They share the same file list, so you don’t need to worry about mixing them – a file included with require_once() will not be included again by include_once().

Note: include_once() and require_once() are statements, not functions. You don’t need parentheses around the filename to be included.

php Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for ProjectPier compliance and the most portable way to include PHP code on differing operating systems and setups.

Note: the final ?> should be omitted from all code files--modules, includes, etc. The closing delimiter is optional, and removing it helps prevent unwanted white space at the end of files which can cause problems elsewhere in the system. The reasons can be summarized as:

  • Removing it eliminates the possibility for unwanted whitespace at the end of files which can cause "header already sent" errors, XHTML/XML validation issues, and other problems.
  • The closing delimiter at the end of a file is optional.
  • PHP.net itself removes the closing delimiter from the end of its files ( example: prepend.inc ), so this can be seen as a "best practice".

Example Urls

Use example.com for all example URLs, per RFC 2606.

Naming Conventions

Functions and Methods

Functions and class members should be named using lower case and words should be separated with an underscore. Functions should in addition have the grouping/module name as a prefix, to avoid name collisions between modules.

Class names and Class Methods

Class names and class methods names should be named using CamelCase notation:

class MyCoolClass {
  private $var_name;
  public function getVarName() {
    return $this->var_name;
  }
}

Constants

Constants should always be ALL_UPPERCASE, with underscores to separate words. Prefix constant names with the uppercased name of the module they are a part of.

Globals

It is highly discouraged to use global variables. If you absolutely require to define global variables, their name should start with a single underscore followed by the module/theme name and another underscore.

Filenames

All documentation files should have the filename extension .txt to make viewing them on Windows systems easier. Also, the filenames for such files should be ALL-CAPS (e.g. README.txt instead of readme.txt) while the extension itself is all-lowercase (i.e. txt instead of TXT).

Examples:

  • README.txt
  • INSTALL.txt
  • TODO.txt
  • CHANGELOG.txt
  • etc.

Error Reporting

Functions should always endeavor to return a reasonable value. Additionally, code should be written to comply with E_ALL wherever possible.

Clone this wiki locally