Manual:Coding conventions

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. It is meant to be descriptive, not dictatorial. If you do choose to follow these guidelines, it will probably be easier for you to collaborate with others on the project, but if you want to contribute in your own style by all means do so (though don't be surprised if your code gets reformatted at a later date).

Basic structure
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.

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.

All text files are encoded with UTF-8. Be sure that your editor supports this.

Do not use MS Notepad to edit files. Notepad inserts unicode byte order marks which stop PHP files from working.

Indenting and alignment
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.

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:

Mid-line vertical alignment should be achieved with spaces. For instance this:

Is achieved as follows with spaces rendered as dots:

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

In general, you should avoid using vertical alignment, since 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.

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:

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

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

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.

Assignment expressions
Using assignment as an expression is surprising to the reader and looks like an error. Do not write code like this:

Space is cheap, and you're a fast typist, so please...

There used to be a reason to use assignment in a while condition, for iteration:

This is unnecessary in new code. Thanks to the wonders of PHP 5, you can now write:

Ternary operator
The ternary operator can be used profitably if the expressions are very short and obvious:

But if you're considering a multi-line expression with a ternary operator, please consider using an "if" block instead. Remember, disk space is cheap, code readability is everything, "if" is English and ?: is not.

Homesick C developers
The PHP language was designed by people who love C and wanted to bring souvenirs from that language into PHP. But PHP has some important differences from C.

In C, constants are implemented as preprocessor macros and are fast. In PHP, they are implemented by doing a runtime hashtable lookup for the constant name, and are slower than just using a string literal. In most places where you would use an enum or enum-like set of macros in C, you can use string literals in PHP.

PHP has three special literals: true, false and null. Homesick C developers write null as NULL because they want to believe that it is a macro defined as ((void*)0). This is not necessary.

Use "elseif" not "else if".

emacs style
In emacs (see also php-mode), you can approximate this style with a custom minor mode in your .emacs file, i.e.

(add-hook 'php-mode-hook 'mw-mode)

Classes

 * As a holdover from PHP 4.x's lack of private class members and methods, older code will be marked with comments such as /** @private */ to indicate the intention; please respect this as if it were enforced by the compiler
 * Newer code will use proper visibilities, but do not add it to existing code without first checking, testing and refactoring as required, because the above rule has been broken in several places
 * In general, member variables are named mXxx to distinguish them, which helps spot missing instances of $this, which will cause odd breakage due to PHP's silent initialisation of the variable
 * We prefix the names of global variables with wg (wiki global) in order to make it easier to distinguish them, which thus makes it easier to spot missing global declarations

Naming conventions
There is a preference for lowerCamelCase when naming functions or variables. For example:

There are also some prefixes used in different places:

Functions

 * wf (wiki functions) - Top-level functions, e.g.

Variables

 * wg - global variables, e.g. ,
 * m - object member variables:
 * This is not universally observed, but try to stay consistent within a class.

Extension Functions and Variables

 * ef - extension functions : top-level functions added by user extensions
 * eg - extension globals

HTTP and session stuff

 * ws - Session variables, e.g.
 * wc - Cookie variables, e.g.
 * wp - Post variables (submitted via form fields), e.g.

Database

 * Table names are usually singular nouns: user, page, revision, etc
 * Except when they're not: pagelinks, categorylinks</tt>...
 * Column names are given a prefix derived from the table name: the name itself if it's short, or an abbreviation:
 * page -> page_id, page_namespace, page_title...
 * categorylinks -> cl_from, cl_namespace...

Common local variables
It is common to work with an instance of the Database</tt> class; we have a naming convention for these which helps keep track of the nature of the server to which we are connected. This is of particular importance in replicated environments, such as Wikimedia and other large wikis.


 * - a Database object for writing (a master connection)
 * - a Database object for non-concurrency-sensitive reading (may be a read-only slave, slightly behind master state)

Inline documentation

 * The Doxygen documentation style is used (it is very similar to PHPDoc for the subset that we use). For example: giving a description of a function or method, the parameters it takes (using ), and what the function returns (using  ), or the   or   tags. Please use "@" rather than "\" as the escape character (e.g. use  ) - both styles work in Doxygen, but the   style does not.


 * General format for parameters is such:  so make sure you don't put   before.

Messages

 * When creating a new message, use hyphens (-) where possible. 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) need to handle colons in a different way, which is impossible if the colon is hardcoded.
 * HTML class and ID names should be prefixed with "mw-". It seems most common to hyphenate them after that, like "mw-some-new-class" instead of "mw-somenewclass" or "mw-some_new_class", but there doesn't appear to be a clear convention at present.

To do

 * Intra-bracket spaces, spaces generally.
 * Blocks without braces, single-line if
 * Single and double quotes, concatenation versus interpolation
 * Naming
 * Function parameter choice