Manual:Coding conventions

This page describes the coding conventions used within the code>Special:MyLanguage/Manual:Code|MediaWiki codebase and extensions which are intended for use on Wikimedia websites, including appropriate naming conventions.

Changes that do not comply with these conventions may be summarily -1'ed by review>Gerrit/Code review|code reviewers; this should be considered an invitation to fix the stylistic issues and update the patch.

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:


 * SVG
 * SVG

On wikitech (applies at least to operations/puppet):


 * tech-puppet>wikitech:Puppet_coding|Puppet

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.

For vim users, one way to establish these settings is to add the following to $HOME/.vimrc:

autocmd Filetype php setlocal ts=4 sw=4

with similar lines for CSS, HTML, and JavaScript.

However, for Python, instead follow the whitespace guidelines from [http://www.python.org/dev/peps/pep-0008/ PEP 8], which recommends spaces for new projects.

Newlines
All files should use Unix-style newlines (single LF character, not a CR+LF combination).


 * git on Windows will (by default) convert CR+LF newlines to LF during committing.

All files should have a newline at the end.


 * It makes sense since all other lines have a newline character at the end.


 * It makes passing data around in non-binary formats (like diffs) easier.


 * Command-line tools like cat and wc don't handle files without one well (or at least, not in the way that one would like or expect).

Encoding
All text files must be encoded with UTF-8 without a Byte Order Mark.

Do not use Microsoft Notepad to edit files, as it always inserts a BOM. A BOM will stop PHP files from working since it is a special character 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.

Trailing whitespace
When using an IDE, pressing the Home and End keys (among other keyboard shortcuts) usually ignores trailing whitespace and instead jumps to the end of the code, which is intended. In non-IDE text editors, though, pressing End will jump to the very end of the line, which means the developer must backspace through the trailing whitespace to get to the spot where they actually want to type.

Removing trailing whitespace is a trivial operation in most text editors. Developers should avoid adding trailing whitespace, primarily on lines that contain other visible code.

Some tools make it easier:


 * nano: GNU nano 3.2;


 * : in the Save Options from menu "Edit > Preferences", enable "Clean trailing whitespace and EOL markers" and "Only clean changed lines";


 * Kate: you can see trailing spaces by enabling the option "Highlight trailing spaces". This option can be found in "Settings > Configure Kate > Appearance". You can also tell Kate to cleanup trailing spaces on save in "Settings > Configure Kate > Open/Save".


 * vim: various automatic cleanup plugins;


 * Sublime Text: [https://github.com/SublimeText/TrailingSpaces TrailingSpaces plugin].

Keywords
Do not use parentheses with keywords (e.g.  ,  ) where they are not necessary.

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. The else/elseif is placed on the same line as the previous closing brace.

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:

In switch statements indent within the braces and between cases:

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.

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

Is achieved as follows with spaces rendered as dots:

 $namespaceNames·=·[ → NS_MEDIA············=>·'Media', → NS_SPECIAL··········=>·'Special', → NS_MAIN·············=>·'', ];

(If you use the [https://github.com/godlygeek/tabular</> tabular vim add-on], entering :Tabularize /= will align the '=' signs.)

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 should be placed at the end of the preceding line.

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.

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.

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:

Later changed to:

This has the potential to create subtle bugs.

emacs style
In emacs, using  from [<tvar|nxhtml>http://ourcomments.org/Emacs/nXhtml/doc/nxhtml.html</> nXHTML mode], you can set up a MediaWiki minor mode in your .emacs file:

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

Constructing URLs
Never build URLs manually with string concatenation or similar. Always use the full URL format for requests made by your code (especially POST and background requests).

You can use the appropriate <tvar|Linker></> or <tvar|Title></> method in PHP, the <tvar|fullurl></> magic word in wikitext, the mw.util.getURL method in JavaScript, and similar methods in other languages. You'll avoid issues with unexpected man>Special:MyLanguage/Manual:Short URL</>|short URL configuration and more.

File naming
Files which contain server-side code should be named in UpperCamelCase. This is also our naming convention for dev-ext>Special:MyLanguage/Manual:Developing extensions</>|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 example,  contains only the   class;   contains the   class, and also its descendants   and.

Access point files
Name "access point" files, such as SQL, and PHP entry points such as  and , 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.

JS, CSS, and media files
For JavaScript, CSS and media files (usually loaded via loader>Special:MyLanguage/ResourceLoader</>|ResourceLoader) file naming should match module naming. For example:
 * Module  might have files   and
 * module  has file

Modules names registered by extensions should follow name like, for instance:

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

Documentation
The language-specific subpages have more information on the exact syntax for code comments in files, e.g. 1>Special:MyLanguage/Manual:Coding conventions/PHP#Comments and documentation</>|comments in PHP for doxygen.

Using precise syntax allows us to generate documentation from source code at http://doc.wikimedia.org.

Some elements of MediaWiki are documented in core's. For instance, if you add a new hook, you should update with the name of the hook, a description of what the hook does, and the parameters used by the hook.

Text files
Developers can keep documentation files in Git alongside code.

This can be good for detailed documentation of extension architecture, database design, etc. that you should update with each code commit that changes behavior.

Pages on mediawiki.org that relate to documentation in Git should link to it using.

(The possibility to transclude text from Git files into wiki pages is tracked in T91626.)

Note that many technical documentation pages on mediawiki.org pages document the evolution of MediaWiki code over many releases.

Either describe changes in your document or state it only describes the latest codebase in "master".

Text file formats

 * If your text file is wikitext, give it a  extension.  GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer).
 * If your text file is wikitext, give it a  extension.  GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer).

For example, the Wikibase extension's  in [<tvar|url>https://github.com/wikimedia/mediawiki-extensions-Wikibase/blob/master/docs/lua.wiki</> GitHub].


 * Doxygen [<tvar|mdurl>http://www.stack.nl/~dimitri/doxygen/manual/markdown.html</> supports Markdown formatting], so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's <tvar|path> </>, in <tvar|Git></> and on <tvar|GitHub>GitHub</>).
 * Doxygen [<tvar|mdurl>http://www.stack.nl/~dimitri/doxygen/manual/markdown.html</> supports Markdown formatting], so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's <tvar|path> </>, in <tvar|Git></> and on <tvar|GitHub>GitHub</>).


 * no extension and
 * Doxygen by default parses these as C language files (!!, tracked in <tvar|bug></>). You can take advantage of this by making the file mimic a C comment, and then add doxygen directives to the file. For example, <tvar|file></> generates [<tvar|url>https://doc.wikimedia.org/mediawiki-core/master/php/group__FileBackend.html#file_backend_design</> File backend design in doxygen], and begins with:




 * Special:Version/Credits assumes  and   (with no extension) are wikitext files.

Source file headers
In order to be compliant with most licenses you should have something similar to the following (specific to GPLv2 PHP applications) at the top of every source file.

Licenses
Licenses are generally referred to by their full name or acronym as per SPDX standard. See also license>Special:MyLanguage/Manual:$wgExtensionCredits#license</>|Manual:$wgExtensionCredits#license.

Release notes
You must document all significant changes (including [<tvar|fixed-bugs>http://article.gmane.org/gmane.science.linguistics.wikipedia.technical/65130</> all fixed bug reports]) to the core software which might affect wiki users, server administrators, or extension authors in the  file. is in development; on every release we move the past release notes into the  file and start afresh. is generally divided into three sections:


 * Configuration changes is the place to put changes to accepted default behavior, 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 behavior which is accepted to be problematic or undesirable. These will often be issues reported in Phabricator, but needn't necessarily.
 * New features is, unsurprisingly, to note the addition of new functionality.

There may be additional sections for specific components (e.g. the 1>Special:MyLanguage/API:Main page</>|Action API) or for miscellaneous changes that don't fall into one of the above categories.

In all cases, if your change is in response to one or more issues reported in Phabricator, include the task ID(s) at the start of the entry. Add new entries in chronological order at the end of the section.

System messages
When creating a new sys-msg>Special:MyLanguage/Manual:system message</>|system message, use hyphens (-) where possible instead of CamelCase or snake_case. So for example,  is a good name, while   and   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. 1>Special:MyLanguage/i18n#Symbols, colons, brackets, etc. are parts of messages</>|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  will not find this use of the message key if they are not used as a whole.

If you feel that you have to build messages on the fly, put a comment with all possible whole messages nearby:

See local>Special:MyLanguage/Localisation</>|Localisation for more conventions about creating, using, documenting and maintaining message keys.

Preferred spelling
It is just as important to have consistent spelling in the UI and codebase as it is to have consistent UI. By long standing history, 'American English' is the preferred spelling for English language messages, comments, and documentation.

Abbreviations in message keys

 * ph
 * placeholder (text in input fields)


 * tip
 * tooltip text


 * tog-xx
 * toggle options in user preferences

Punctuation
Non-title error messages are considered as sentences and should have punctuation.

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

Core modules
If you need some additional functionality of a core module (or you need a function that does something similar but a different), actually improve the core module. Don't just copy+paste and modify the code in another place.

Refactoring
Refactor code as changes are made: don't let the code keep getting worse with each change.

However, use separate commits if the refactoring is large. See also arch-guide>Special:MyLanguage/Architecture guidelines</>|Architecture guidelines (draft).

HTML
MediaWiki HTTP responses output HTML that can be generated by one of two sources. The MediaWiki PHP code is a trusted source for the user interface, it can output any arbitrary HTML. The Parser converts user-generated wikitext into HTML, this is an untrusted source. Complex HTML created by users via wikitext is often found in the "Template" namespace. HTML produced by the Parser is subject to sanitization before output.

Most data attributes are allowed to be used by users in wikitext and templates. But, the following prefixes have been restricted and are not allowed in wikitext. This enables client JavaScript code to determine whether a DOM element came from a trusted source:


 * – This attribute is present in HTML generated by OOUI widgets.


 * – reserved attribute for internal use by Parsoid.


 * and  – reserved attribute for internal use by MediaWiki core, skins and extensions. The   is also used by Parsoid.

When selecting elements in JavaScript, one can specify an attribute key/value to ensure only DOM elements from the intended trusted source are considered.

Example: Only trigger 'wikipage.diff' hook for official diffs.