Drupal Coding Standards (6/2/2009)

Article taken from Drupal.org Coding Standards (RECOMMENDED - read from drupal.org site, as it will be the most updated version as well as properly formatted)

Coding standards

Last modified: February 6, 2009 - 17:03

Note: The Drupal Coding Standards applies to code within Drupal and its contributed modules. This document is based on the PEAR Coding standards. Comments and names should use US English spelling ("color" not "colour" etc.).

Indenting

Use an indent of 2 spaces, with no tabs. No trailing whitespace.

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

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

Function Declarations

function funstuff_system($field) {
$system["description"] = t("This module inserts funny text into posts randomly.");
return $system[$field];
}

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' => t('Title'),
'#size' => 60,
'#maxlength' => 128,
'#description' => t('The title of your node.'),
);

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.

Quotes

Things like "single quotes vs double quotes" are features of PHP itself to make programming easier and there are no reasons not use one way in preference to another. Such best practices are left solely on developer to decide. Where possible, keep consistency within each module and respect the personal style of other developers.

With that caveat in mind: single quote strings are known to be faster because the parser doesn't have to look for in-line variables. Their use is recommended except in two cases:

1. In-line variable usage.
2. Translated strings where one can avoid escaping single quotes by enclosing the string in double quotes. One such string would be "He's a good person." It would be 'He\'s a good person.' with single quotes. Such escaping may not be handled properly by .pot file generators for text translation.

String concatenations

Always use a space between the dot and the concatenated parts to improve readability.

= 'Foo' . $bar;
$string = $bar . 'foo';
$string = bar() . 'foo';
$string = 'foo' . 'bar';
?>

When you concatenate simple variables, you can use double quotes and add the string inside, otherwise use single quotes.

= "Foo $bar";
?>

When using the concatenating assignment operator ('.='), use a space on each side as with the assignment operator:

.= 'Foo';
$string .= $bar;
$string .= baz();
?>

Comments

Inline documentation for source files should follow the Doxygen formatting conventions.

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.

Non-documentation comments should use capitalized sentences with punctuation. Sentences should be separated by single spaces. All caps are used in comments only when referencing constants, for example TRUE. Comments should be on a separate line immediately before the code line or block they reference. For example:

// Unselect all other contact categories.
db_query('UPDATE {contact} SET selected = 0');

If each line of a list needs a separate comment, the comments may be given on the same line and may be formatted to a uniform indent for readability.

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

Including Code

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 file name to be included.

PHP Code Tags

Always use to delimit PHP code, not the
shorthand, . This is required for Drupal compliance and is also the most portable way to include PHP code on differing operating
systems and set-ups.

Note that as of Drupal 4.7, the ?> at the end of code files is purposely omitted. This includes for module and include files. The reasons for this 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."

Header Comment Blocks

All source code files in the core Drupal distribution should
contain the following comment block as the header:

This tag will be expanded by the CVS to contain useful information

Using CVS

Include the Id CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.).

The rest of this section assumes that you have basic knowledge about CVS tags and branches.

CVS tags are used to label which revisions of the files in your package belong to a given release. Below is a list of the required CVS tags:

DRUPAL-X-Y

(required) Used for tagging a release. If you don't use it, there's no way to go back and retrieve your package from the CVS server in the state it was in at the time of the release.

Example URLs

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

Naming Conventions

Functions and Methods

Functions and methods should be named using lowercase 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.

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; PHP 4 does not support truly-enforceable private namespaces) are preceded by a single underscore. For example:

_node_get()

$this->_status

Constants

Constants should always be all-uppercase, with underscores to separate words. This includes pre-defined PHP constants like TRUE, FALSE, and NULL. Module-defined constant names should also be prefixed by an uppercase spelling of the module they are defined by.

Global Variables

If you need to define global variables, their name should start with a single underscore followed by the module/theme name and another underscore.

Class Names

Though classes are rarely used in Drupal, their name should use "studlyCaps." For example:

$type = new stdClass();


File names

All documentation files should have the file name extension ".txt" to make viewing them on Windows systems easier. Also, the file names 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.

Helper Script

There is a helper command line script included with Drupal to check your code for style compliance. The code-style.pl file is located in the /scripts. To use the script just give your file as an argument when you execute the script (make sure the script is executable):

./code-style.pl path/to/file/example.module

This will output a list of suggestions for where to improve your code. You will need to make the actual changes to the code yourself.

Helper Module

There is a contributed module for assisting with code review. To use this module you must complete the following steps:

• Install the coder module.
• Click on the "Code Review" link in your navigation menu
• Scroll down to "Select Specific Modules"
• select the module you wish to review, and click the "Submit" button.

Read More on Drupal.org

4 Ace Technologies