Manual:Coding conventions

From MediaWiki.org
(Redirected from CC)
Jump to: navigation, search
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. Changes that do not comply with these conventions may be summarily -1'ed by 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:

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

Code structure[edit | edit source]

File formatting[edit | edit source]

Tab size[edit | edit source]

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 PEP 8, which recommends spaces for new projects.

Newlines[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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 he/she actually wants 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: craigbarnes/nanorc;
  • Komodo Edit: in the Save Options from menu "Edit > Preferences", enable "Clean trailing whitespace and EOL markers" and "Only clean changed lines";
  • kate: enable highlighting in settings > configure > aspect;
  • vim: various automatic cleanup plugins;
  • sublime: [1].

Indenting and alignment[edit | edit source]

General style[edit | edit source]

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[edit | edit source]

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.

Most diff tools provide options to ignore whitespace changes.
Git: git diff -w

When needed, create mid-line vertical alignment with spaces rather than tabs. 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·············=>·'',

(If you use the tabular vim add-on, entering :Tabularize /= will align the '=' signs.)

Line continuation[edit | edit source]

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:

$foo->dobar(
    Xml::fieldset( wfMessage( 'importinterwiki' )->text() ) .
        Xml::openElement( 'form', array( 'method' => 'post', 'action' => $action, 'id' => 'mw-import-interwiki-form' ) ) .
        wfMessage( 'import-interwiki-text' )->parse() .
        Xml::hidden( 'action', 'submit' ) .
        Xml::hidden( 'source', 'interwiki' ) .
        Xml::hidden( 'editToken', $wgUser->editToken() ),
    'secondArgument'
);

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.

Braceless control structures[edit | edit source]

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[edit | edit source]

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 mah/mw-mode
  "tweak style for mediawiki"
  nil " MW" nil
  (delete-trailing-whitespace)
  (tabify (point-min) (point-max))
  (subword-mode 1)) ;; If this gives an error, try (c-subword-mode 1)), which is the earlier name for it
 
;; 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.

eclipse style[edit | edit source]

There is an eclipse plugin called PDT Extensions that is helpful for formatting the code. A formatting template can be downloaded here.

File naming[edit | edit source]

Files which contain server-side code should be named in UpperCamelCase. This is also our naming convention for extensions.[1] 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.

Source file headers[edit | edit source]

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.

<?php
/**
 * This file is part of the CentralNotice Extension to MediaWiki
 * https://www.mediawiki.org/wiki/Extension:CentralNotice
 *
 * @section LICENSE
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 * 
 * @file
 */

Release notes[edit | edit source]

All significant changes (which includes all fixed bug reports) 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[edit | edit source]

When creating a new system message, use hyphens (-) where possible instead of CamelCase or snake_case. 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 wfMessage( 'templatesused-' . ( $section ? 'section' : 'page' ) );
 
// Yes:
$msgKey = $section ? 'templatesused-section' : 'templatesused-page';
return wfMessage( $msgKey );

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

// Messages that can be used here:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

See Localisation for more conventions about creating, using, documenting and maintaining message keys.

Preferred spelling[edit | edit source]

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[edit | edit source]

ph
placeholder (text in input fields)
tip
tooltip text
tog-xx
toggle options in user preferences

Punctuation[edit | edit source]

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

ResourceLoader[edit | edit source]

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

Documentation[edit | edit source]

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.

Notes[edit | edit source]

  1. mailarchive:wikitech-l/2011-August/054839.html

External links[edit | edit source]

Conventions
General All languages · Security for developers · Pre-commit checklist · Performance guidelines (draft) · Style guide (draft) · Accessibility guide for developers (draft)
PHP Code conventions · PHPUnit test conventions · Security checklist for developers
JavaScript Code conventions · Learning JavaScript
CSS Code conventions
Database Code conventions
Python Code conventions
Selenium/Cucumber Code conventions
Language: English  • français • 日本語