Manual:Coding conventions

shortcut CC

This page describes the coding conventions used within the MediaWiki codebase and extensions which are intended for use on Wikimedia websites, including appropriate naming conventions.

This page lists general conventions that apply to all MediaWiki code, whatever language it is written in. For guidelines that apply to specific components or file types in MediaWiki, see:

• PHP
• JavaScript
• CSS
• Database

Code structure

File formatting

Tab size

Lines should be indented with a single tab character per indenting level. You should make no assumptions about the number of spaces per tab. Most MediaWiki developers find 4 spaces per tab to be best for readability, but many systems are configured to use 8 spaces per tab and some developers might use 2 spaces per tab.

Newlines

All text files should be checked in to Subversion with svn:eol-style set to "native". This is necessary to prevent corruption by certain Windows-based text editors.

You can ask subversion to automatically set this property on a given list of file type. This is done with subversion auto-props and will save you the hassle to manually set the property when adding new files.

You might want to read the English Wikipedia article about newline.

Encoding

All text files must be encoded with UTF-8 without byte order marks.

Do not use Microsoft Notepad to edit files. Notepad always inserts BOM. BOM will stop PHP files from working since it is a special character inserted at the very top of the file and will be output by the web browser to the client.

In short, make sure your editor supports UTF-8 without BOM.

Indenting and alignment

General style

MediaWiki's indenting style is similar to the so-called "One True Brace Style". Braces are placed on the same line as the start of the function, conditional, loop, etc.

function wfTimestampOrNull( $outputtype = TS_UNIX, $ts = null ) {
        if ( is_null( $ts ) ) {
                return null;
        } else {
                return wfTimestamp( $outputtype, $ts );
        }
}

Multi-line statements are written with the second and subsequent lines being indented by one extra level:

Use indenting and line breaks to clarify the logical structure of your code. Expressions which nest multiple levels of parentheses or similar structures may begin a new indenting level with each nesting level:

$wgAutopromote = array(
        'autoconfirmed' => array( '&',
                array( APCOND_EDITCOUNT, &$wgAutoConfirmCount ),
                array( APCOND_AGE, &$wgAutoConfirmAge ),
        ),
);

There are some exceptions, such as switch statements, where the indentation of the cases are optional, so both of the below are fine.

switch ( $word ) {
case 'lorem':
case 'ipsum':
        $bar = 2;
        break;
case 'dolor':
        $bar = 3;
        break;
default:
        $bar = 0;
}

var bar;
switch ( word ) {
        case 'lorem':
        case 'ipsum':
                bar = 2;
                break;
        case 'dolor':
                bar = 3;
                break;
        default:
                bar = 0;
}

Vertical alignment

Avoid vertical alignment. It tends to create diffs which are hard to interpret, since the width allowed for the left column constantly has to be increased as more items are added.

Note: Most diff tools provide options to ignore whitespace. For Subversion, the -X -w flag makes the svn diff command ignore all whitespace.

When needed, create mid-line vertical alignment with spaces. For instance this:

$namespaceNames = array(
        NS_MEDIA            => 'Media',
        NS_SPECIAL          => 'Special',
        NS_MAIN             => '',

Is achieved as follows with spaces rendered as dots:

$namespaceNames·=·array(
   →    NS_MEDIA············=>·'Media',
   →    NS_SPECIAL··········=>·'Special',
   →    NS_MAIN·············=>·'',

Line continuation

Lines should be broken at between 80 and 100 columns. There are some rare exceptions to this. Functions which take lots of parameters are not exceptions.

The operator separating the two lines may be placed on either the following line or the preceding line. An operator placed on the following line is more visible and so is more often used when the author wants to draw attention to it:

return strtolower( $val ) == 'on'
        || strtolower( $val ) == 'true'
        || strtolower( $val ) == 'yes'
        || preg_match( "/^\s*[+-]?0*[1-9]/", $val );

An operator placed on the preceding line is less visible, and is used for more common types of continuation such as concatenation and comma:

$wgOut->addHTML(
        Xml::fieldset( wfMsg( 'importinterwiki' ) ) .
        Xml::openElement( 'form', array( 'method' => 'post', 'action' => $action, 'id' => 'mw-import-interwiki-form' ) ) .
        wfMsgExt( 'import-interwiki-text', array( 'parse' ) ) .
        Xml::hidden( 'action', 'submit' ) .
        Xml::hidden( 'source', 'interwiki' ) .
        Xml::hidden( 'editToken', $wgUser->editToken() ) .
);

When continuing "if" statements, a switch to Allman-style braces makes the separation between the condition and the body clear:

if ( $.inArray( mw.config.get( 'wgNamespaceNumber' ), whitelistedNamespaces ) !== -1
        && mw.config.get( 'wgArticleId' ) > 0
        && ( mw.config.get( 'wgAction' ) == 'view' || mw.config.get( 'wgAction' ) == 'purge' )
        && mw.util.getParamValue( 'redirect' ) !== 'no'
        && mw.util.getParamValue( 'printable' ) !== 'yes'
) {
        ..
}

Opinions differ on the amount of indentation that should be used for the conditional part. Using an amount of indentation different to that used by the body makes it more clear that the conditional part is not the body, but this is not universally observed.

Continuation of conditionals and very long expressions tend to be ugly whichever way you do them. So it's sometimes best to break them up by means of temporary variables.

Spaces

MediaWiki favors a heavily-spaced style for optimum readability.

Put spaces on either side of binary operators, for example:

// No:
$a=$b+$c;
 
// Yes:
$a = $b + $c;

Put spaces next to parentheses on the inside, except where the parentheses are empty. Do not put a space following a function name.

$a = getFoo( $b );
$c = getBar();

Opinions differ as to whether control structures if, while, for and foreach should be followed by a space; the following two styles are acceptable:

// Spacey
if ( isFoo() ) {
        $a = 'foo';
}
 
// Not so spacey
if( isFoo() ) {
        $a = 'foo';
}

Single-line comments should have a space between the # or // and the comment text.

To help developers fix code with an inadequately spacey style, a tool called stylize.php has been created, which uses PHP's tokenizer extension to add spaces at the relevant places.

Braceless control structures

Do not write "blocks" as a single-line. They reduce the readability of the code by moving important statements away from the left margin, where the reader is looking for them. Remember that making code shorter doesn't make it simpler. The goal of coding style is to communicate effectively with humans, not to fit computer-readable text into a small space.

// No:
if ( $done ) return;
 
// No:
if ( $done ) { return; }
 
// Yes:
if ( $done ) {
        return;
}

This avoids a common logic error, which is especially prevalent when the developer is using a text editor which does not have a "smart indenting" feature. The error occurs when a single-line block is later extended to two lines:

if ( $done )
        return;

Later changed to:

if ( $done )
        $this->cleanup();
        return;

This has the potential to create subtle bugs.

emacs style

In emacs, using php-mode.el from nXHTML mode, you can set up a MediaWiki minor mode in your .emacs file:

(defconst mw-style
  '((indent-tabs-mode . t)
    (tab-width . 4)
    (c-basic-offset . 4)
    (c-offsets-alist . ((case-label . +)
                        (arglist-cont-nonempty . +)
                        (arglist-close . 0)
                        (cpp-macro . (lambda(x) (cdr x)))
                        (comment-intro . 0)))
    (c-hanging-braces-alist
        (defun-open after)
        (block-open after)
        (defun-close))))
 
(c-add-style "MediaWiki" mw-style)
 
(define-minor-mode mw-mode
  "tweak style for mediawiki"
  nil " MW" nil
  (delete-trailing-whitespace)
  (tabify (point-min) (point-max))
  (c-subword-mode 1))
 
;; Add other sniffers as needed
(defun mah/sniff-php-style (filename)
  "Given a filename, provide a cons cell of
   (style-name . function)
where style-name is the style to use and function
sets the minor-mode"
  (cond ((string-match "/\\(mw[^/]*\\|mediawiki\\)/"
                       filename)
         (cons "MediaWiki" 'mah/mw-mode))
        (t
         (cons "cc-mode" (lambda (n) t)))))
 
(add-hook 'php-mode-hook (lambda () (let ((ans (when (buffer-file-name)
                                                 (mah/sniff-php-style (buffer-file-name)))))
                                      (c-set-style (car ans))
                                      (funcall (cdr ans) 1))))

The above mah/sniff-php-style function will check your path when php-mode is invoked to see if it contains “mw” or “mediawiki” and set the buffer to use the mw-mode minor mode for editing MediaWiki source. You will know that the buffer is using mw-mode because you'll see something like “PHP MW” or “PHP/lw MW” in the mode line.

File naming

Files which contain server-side code should be named in UpperCamelCase. This is also our naming convention for extensions. Name the file after the most important class it contains; most files will contain only one class, or a base class and a number of descendants. For instance, Title.php contains only the Title class; HTMLForm.php contains the base class HTMLForm, but also the related class HTMLFormField and its descendants.

Name 'access point' files, such as SQL, and PHP entry points such as index.php and foobar.sql, in lowercase. Maintenance scripts are generally in lowerCamelCase, although this varies somewhat. Files intended for the site administrator, such as readmes, licenses and changelogs, are usually in UPPERCASE.

Never include spaces in file names or directories, and never use non-ASCII characters. For lowercase titles, hyphens are preferred to underscores.

For JavaScript, CSS and media files (usually loaded via ResourceLoader) file naming should match module naming. For example:

• module mediawiki.foo has files resources/mediawiki.foo/mediawiki.foo.js and resources/mediawiki.foo/mediawiki.foo.css
• module mediawiki.Title has file resources/mediawiki/mediawiki.Title.js

JS and CSS files for extensions usually use a name like ext.myExtension, for instance:

• extensions/FooBar/resources/ext.fooBar/ext.fooBar.init.js

This keeps it easy to find things, even if you divide up a module into smaller files for editing convenience and then bundle them together into a single module.

Groups of modules should have their files also grouped in directories. For example, there are several modules related to "jquery". All those modules start with "jquery." and are stored in the resources/jquery directory.

Release notes

All significant changes to the core software which might affect wiki users, server administrators, or extension authors, must be documented in the RELEASE-NOTES file. This file is refreshed on every release (with the past content going into HISTORY) and is generally divided into three sections:

• Configuration changes is the place to put changes to accepted default behaviour, backwards-incompatible changes, or other things which need a server administrator to look at and decide "is this change right for my wiki?". Try to include a brief explanation of how the previous functionality can be recovered if desired.
• Bug fixes is the place to note changes which fix behaviour which is accepted to be problematic or undesirable. These will often be issues reported in bugzilla, but needn't necessarily.
• New features is, unsurprisingly, to note the addition of new functionality.

In all cases, if your change is in response to an issue reported in bugzilla, include the bug reference at the start of the entry. New entries are added in chronological order at the end of the section.

System messages

When creating a new system message, use hyphens (-) where possible instead of CamelCase or rails_underscored_variables. So for example, some-new-message is a good name, while someNewMessage and some_new_message are not.

If the message is going to be used as a label which can have a colon (:) after it, don't hardcode the colon; instead, put the colon inside the message text. Some languages (such as French which require a space before) need to handle colons in a different way, which is impossible if the colon is hardcoded. The same holds for several other types of interpunctuation.

Try to use message keys "whole" in code, rather than building them on the fly; as this makes it easier to search for them in the codebase. For instance, the following shows how a search for templatesused-section will not find this use of the message key if they are not used as a whole.

// No:
return wfMsg( 'templatesused-' . ( $section ? 'section' : 'page' ) ) );
 
// Yes:
$msgKey = $section ? 'templatesused-section' : 'templatesused-page';
return wfMsg( $msgKey );

ResourceLoader

Module names should match the main definition of the scripts they load. For example a module defining the the mw.util object is named "mediawiki.util" and the module for the mw.Title object constructor is named "mediawiki.Title".

Documentation

Some elements of MediaWiki are documented in the /docs folder. For instance, if you add a new hook, you should update docs/hooks.txt with the name of the hook, a description of what the hook does, and the parameters used by the hook.