CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

When creating internal Drupal arrays, such as menu items or form definitions, always list only one element on each line:

$form['flavors'] = array(

'#description' => t('Choose a flavor.'),

Quotes

Drupal does not have a hard standard for the use of single quotes vs. double quotes. Where possible, keep consistency within each module, and respect personal styles of other developers. With that in mind, there is one caveat: single quote strings are known to be faster because the parser doesn’t have to look for inline variables. Single quotes are recommended except in the following:

1.Inline variable usage, e.g., “<h2>$header</h2>”

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 properly handled by .pot file generators for text translation, and it’s also a little awkward to read.

String Concatenators

You should always use a space between the dot and the concatenated parts to improve readability, as in the following example:

$string = ‘Foo’ . $bar; $string = $bar . ‘Foo’; $string = bar() . ‘Foo’; $string = ‘foo’ . ‘bar’;

When you concatenate simple variables, you can use double quotes and add the variable inside, such as the following example:

$string = "Foo $bar";

Comments

Drupal follows most of the Doxygen comment style guidelines. All documentation blocks must use the following syntax:

/**

* Documentation here. */

491

CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

The leading spaces that appear before the asterisks (*) on lines after the first one are required.

■ Note Doxygen is a PHP-friendly documentation generator. It extracts PHP comments from the code and generates human-friendly documentation. For more information, visit www.doxygen.org.

When documenting a function, the documentation block must immediately precede the function it documents, with no intervening blank lines.

Drupal understands the Doxygen constructs in the following list; although I’ll cover the most common ones, please refer to the Doxygen site for more information on how to use them:

•@mainpage

•@file

•@defgroup

•@ingroup

•@addtogroup (as a synonym of @ingroup)

•@param

•@return

•@link

•@see

•@{

•@}

The beauty of adhering to these standards is that you can automatically generate documentation for your modules using the API contributed module. The API module is an implementation of a subset of the Doxygen documentation generator specification, tuned to produce output that best benefits a Drupal code base. You can see this module in action by visiting http://api.drupal.org, and you can learn more about the API module at http://drupal.org/project/api.

Documentation Examples

Let’s walk through the skeleton of a module from top to bottom and highlight the different types of documentation along the way.

Before declaring functions, take a moment to document what the module does using the following format:

492

CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

/**

*@file

*One-line description/summary of what your module does goes here.

*A paragraph or two in broad strokes about your module and how it behaves.

*/

Documenting Constants

PHP constants should be in all capital letters, with underscores separating proper words. When defining PHP constants, it’s a good idea to explain what they’re going to be used for, as shown in the following code snippet:

/**

* Role ID for authenticated users; should match what's in the "role" table. */

define('DRUPAL_AUTHENTICATED_RID', 2);

Documenting Functions

Function documentation should use the following syntax:

/**

*Short description, beginning with a verb.

*Longer description goes here.

*

*@param $foo

*A description of what $foo is.

*@param $bar

*A description of what $bar is.

*@return

*A description of what this function will return.

*/

function name_of_function($foo, $bar) {

...

return $baz;

}

The short description should begin with an imperative verb in the present tense, such as “Munge form data” or “Do remote address lookups” (not “Munges form data” or “Does remote address lookups”). Let’s take a look at an example from Drupal core that is found within system.module:

493

CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

/**

*Add default buttons to a form and set its prefix.

*@param $form

*An associative array containing the structure of the form.

*@return

*The form structure.

*

*@see system_settings_form_submit()

*@ingroup forms

*/function system_settings_form($form) {

...

}

There are a couple of new Doxygen constructs in the preceding example:

•@see tells you what other functions to reference. The preceding code is a form definition, so @see points to the submit handler for the form. When the API module parses this to produce documentation (such as that available at http://api.drupal.org), it will turn the function name that follows @see into a clickable link.

•@ingroup links a set of related functions together. In this example, it creates a group of functions that provide form definitions. You can create any group name you wish. Possible core values are: batch, database, file, format, forms, hooks, image, menu, node_access, node_content, schemaapi, search, themeable, and validation.

■Tip You can view all functions in a given group at http://api.drupal.org. For example, form builder functions are listed at http://api.drupal.org/api/group/forms/7, and themable functions are listed at

http://api.drupal.org/api/group/themeable/7.

Functions that implement common Drupal constructs, such as hooks or form validation/ submission functions, may omit the full @param and @return syntax but should still contain a one-line description of what the function does, as in this example:

/**

*Validate the book settings form.

*@see book_admin_settings()

*/

function book_admin_settings_validate($form, &$form_state) {

...

}

}

494