Joomla Coding Standards

Good coding standards are important in any software development project. These standards are even more important when a large, diverse and worldwide community of developers are contributing to a project.

The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it is deemed sensible to do so.

Doctype

Always use the minimal doctype.

<!doctype html>

Language

Always define which language the page is written in.

<html lang="en">

Encoding

Always define the character encoding. The encoding should be defined as early as possible. Make sure your editor uses UTF-8 as character encoding Do not specify the encoding of style sheets as these assume UTF-8.

<meta charset="utf-8">

Capitalisation

All HTML should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings). Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness in XHTML.

Type and Language attributes

Do not use type or attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript). Do not use language attributes on script tags.

Attributes

Attribute values should be quoted using double ("") quotes. Optional attributes should be omitted. Use attribute and value pairs for boolean attributes.

HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.

  • class
  • id
  • data-*
  • Everything else

Formatting

Use a new line for every block, list, or table element, and indent every such child element.

Joomla prefers readability over file-size savings when it comes to maintaining existing files. Plenty of whitespace is encouraged. Use whitespace to visually separate groups of related markup and to improve the readability and maintainability of your HTML. Remove trailing white spaces.

Documentation headers

Documentation headers for PHP code in: files, classes, class properties, methods and functions, called the docblocks. The file header DocBlock consists of the following required and optional elements in the following order:

  • @Version (optional and must be first)
  • @category (optional and rarely used)
  • @Package (generally optional but required when files contain only procedural code. Always optional in namespaced code)
  • @subpackage (optional)
  • @author (optional but only permitted in non-Joomla source files)
  • @copyright (required)
  • @license (required and must be compatible with the Joomla license)
  • @link (optional)
  • @see (optional)
  • @SInCE (generally optional but required when files contain only procedural code)
  • @deprecated (optional)
/**
 * @package Joomla.Installation
 * @subpackage Controller
 *
 * @copyright Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.
 * @license GNU General Public License version 2 or later; see LICENSE.txt
 */

PHP Code

Always use the full <?php ... ?> to delimit PHP code.

For files that contain only PHP code, the closing tag (?>) should not be included. It is not required by PHP. Leaving this out prevents trailing white space from being accidentally injected into the output that can introduce errors.

Including Code

Anywhere you are unconditionally including a file, use require_once. Anywhere you are conditionally including a file (for example, factory methods), use include_once. Either of these will ensure that files are included only once. You should not enclose the filename in parentheses.

require_once JPATH_COMPONENT . '/helpers/helper.php';

Global Variables

Global variables should not be used. Use static class properties or constants instead of globals, following OOP and factory patterns.

Control Structures

For all control structures there is a space between the keyword and an opening parenthesis, then no space either after the opening parenthesis or before the closing bracket. This is done to distinguish control keywords from function names. All control structures must contain their logic within braces.

Concatenation Spacing

There should always be a space before and after the concatenation operator ('.').

Arrays

Assignments (the => operator) in arrays may be aligned with spaces. When splitting array definitions onto several lines, the last value should also have a trailing comma.

Function Calls

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis. There should be space before and exactly one space after the equals sign. 

Function Definitions

Function definitions start on a new line with no spaces between the function name and the opening parenthesis. Additionally, the opening and closing braces are also placed on new lines. An empty line should precede lines specifying the return value.

Namespaces

Namespaces are formatted according to this flow. First there is the file docblock followed by the namespace the file lives in. When required, the namespace is followed by the defined check. Lastly, the imported classes using the use keyword. All namespace imports must be alphabetically ordered.

Constants

Constants should always be all-uppercase, with underscores to separate words.