Manual:Coding conventions

From MediaWiki.org
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. If you would like a short checklist to help you review your commits, try using the pre-commit checklist.

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. It's recommended to run this over new files committed to SVN, but not so much for fixing current files.

Contents

[edit] All languages

Some general guidelines apply to all MediaWiki code, whatever language it is written in.

[edit] File formatting

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

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

[edit] 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 outputted by the web browser to the client.

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

[edit] Indenting and alignment

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

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

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 ( $mimetype ) {
        case 'text/xml':
        case 'application/xhtml+xml':
        case 'application/xml':
                return true;
        default:
                return false;
        }

         switch ( $mimetype ) {
                case 'text/xml':
                case 'application/xhtml+xml':
                case 'application/xml':
                        return true;
                default:
                        return false;
        }

[edit] 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·············=>·'',

[edit] 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 ( ( $this->mNamespace != NS_SPECIAL && strlen( $dbkey ) > 255 )
        || strlen( $dbkey ) > 512 )
{
        return false;
}

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.

[edit] Spaces

MediaWiki favours a heavily-spaced style for optimum readability.

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

$a = $b + $c;

not like this:

$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.

[edit] Braceless control structures

Do not use single-line if statements:

if ( $done ) return;
if ( $done ) { return; }

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.

Most MediaWiki developers favour fully-braced control structures:

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.

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

[edit] File naming

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 JS and CSS files loaded via ResourceLoader, file naming should match module naming. For example:

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

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.

[edit] PHP code

[edit] Code structure

[edit] Assignment expressions

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

if ( $a = foo() ) {
    bar();
}

Space is cheap, and you're a fast typist, so instead use:

$a = foo();
if ( $a ) {
    bar();
}

Using assignment in a while() clause used to be legitimate, for iteration:

$res = $dbr->query( 'SELECT * FROM some_table' );
while ( $row = $dbr->fetchObject( $res ) ) {
    showRow( $row );
}

This is unnecessary in new code; instead use:

$res = $dbr->query( 'SELECT * FROM some_table' );
foreach ( $res as $row ) {
    showRow( $row );
}

[edit] Ternary operator

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

$wiki = isset( $this->mParams['wiki'] ) ? $this->mParams['wiki'] : false;

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.

[edit] 5.3 shorthand

Since we still support PHP 5.2.x, use of the shorthand ternary operator introduced in PHP 5.3 is not allowed.

[edit] String literals

For simple string literals, single quotes are slightly faster for PHP to parse than double quotes. Perhaps more importantly, they are easier to type, since you don't have to press shift. For these reasons, single quotes are preferred in cases where they are equivalent to double quotes.

However, do not be afraid of using PHP's double-quoted string interpolation feature: $elementId = "myextension-$index"; This has slightly better performance characteristics than the equivalent using the concatenation (dot) operator, and it looks nicer too.

Heredoc-style strings are sometimes useful:

$s = <<<EOT
<div class="mw-some-class">
$boxContents
</div>
EOT;

Some authors like to use END as the ending token, which is also the name of a PHP function. This leads to IRC conversations like the following:

<Simetrical>      vim also has ridiculously good syntax highlighting.
<TimStarling>     it breaks when you write <<<END in PHP
<Simetrical>      TimStarling, but if you write <<<HTML it syntax-highlights as HTML!
<TimStarling>     I have to keep changing it to ENDS so it looks like a string again
<brion-codereview>        fix the bug in vim then!
<TimStarling>     brion-codereview: have you ever edited a vim syntax script file?
<brion-codereview>        hehehe
<TimStarling>     http://tstarling.com/stuff/php.vim
<TimStarling>     that's half of it...
<TimStarling>     here's the other half: http://tstarling.com/stuff/php-syntax.vim
<TimStarling>     1300 lines of sparsely-commented code in a vim-specific language
<TimStarling>     which turns out to depend for its operation on all kinds of subtle inter-pass effects
<werdnum> TimStarling: it looks like some franken-basic language.

[edit] Functions and parameters

Avoid passing huge numbers of parameters to functions or constructors:

//Constructor for Block.php as of 1.17. *DON'T* do this!
function __construct( $address = '', $user = 0, $by = 0, $reason = '',
        $timestamp = 0, $auto = 0, $expiry = '', $anonOnly = 0, $createAccount = 0, $enableAutoblock = 0,
        $hideName = 0, $blockEmail = 0, $allowUsertalk = 0 )
{
        ...
}

It quickly becomes impossible to remember the order of parameters, and you will inevitably end up having to hardcode all the defaults in callers just to customise a parameter at the end of the list. If you are tempted to code a function like this, consider passing an associative array of named parameters instead.

In general, using boolean parameters is discouraged in functions. In $object->getSomething( $input, true, true, false ), without looking up the documentation for MyClass::getSomething(), it is impossible to know what those parameters are meant to indicate. Much better is to either use class constants, and make a generic flag parameter:

$myResult = MyClass::getSomething( $input, MyClass::FROM_DB & MyClass::PUBLIC_ONLY );

Or to make your function accept an array of named parameters:

$myResult = MyClass::getSomething( $input, array( 'fromDB', 'publicOnly' ) );

Try not to repurpose variables over the course of a function, and avoid modifying the parameters passed to a function (unless they're passed by reference and that's the whole point of the function, obviously).

[edit] C borrowings

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. They have subtly different meanings:

// This:
if( $foo == 'bar' ) {
        echo 'Hello world';
} else if( $foo == 'Bar' ) {
        echo 'Hello world';
} else if( $baz == $foo ) {
        echo 'Hello baz';
} else {
        echo 'Eh?';
}
 
// Is actually equivalent to:
if( $foo == 'bar' ) {
        echo 'Hello world';
} else {
        if( $foo == 'Bar' ) {
                echo 'Hello world';
        } else  {
                if( $baz == $foo ) {
                        echo 'Hello baz';
                } else {
                        echo 'Eh?';
                }
        }
}

And the latter has poorer performance.

[edit] PHP pitfalls

[edit] Integration

There are a few pieces of code in the MediaWiki codebase which are intended to be standalone and easily portable to other applications; examples include the UTF normalisation in /includes/normal and the libraries in /includes/libs. Apart from these, code should be integrated into the rest of the MediaWiki environment, and should allow other areas of the codebase to integrate with it in return.

[edit] Global objects

Do not access the PHP superglobals $_GET, $_POST, etc, directly; use $wgRequest->get*( 'param' ) instead; there are various functions depending on what type of value you want. Equally, do not access $_SERVER directly; use $wgRequest->getIP() if you want to get the IP address of the current user.

[edit] Classes

Encapsulate your code in an object-oriented class, or add functionality to existing classes; do not add new global functions or variables. Try to be mindful of the distinction between 'backend' classes, which represent entities in the database (eg User, Block, Revision, etc), and 'frontend' classes, which represent pages or interfaces visible to the user (SpecialPage, Article, ChangesList, etc. Even if your code is not obviously object-oriented, you can put it in a static class (eg IP or Html).

As a holdover from PHP 4's lack of private class members and methods, older code will be marked with comments such as /** @private */ to indicate the intention; respect this as if it were enforced by the interpreter.

Mark new code with proper visibility modifiers, including public if appropriate, but do not add visibility to existing code without first checking, testing and refactoring as required. It's generally a good idea to avoid visibility changes unless you're making changes to the function which would break old uses of it anyway.

[edit] Error handling

Don't suppress errors with PHP's @ operator, for any reason ever. It's broken when E_STRICT is enabled and it causes an unlogged, unexplained error if there is a fatal, which is hard to support. Use wfSuppressWarnings() and wfRestoreWarnings() instead. The checkSynax.php maintenance script can check for this error for you.

When your code encounters a sudden error, you should throw a MWException (or an appropriate subclass) rather than using PHP's trigger_error. The exception handler will display this as nicely as possible to the end user and wiki administrator, and also provides a stack trace to developers.

[edit] Naming

Use lowerCamelCase when naming functions or variables. For example:

private function doSomething( $userPrefs, $editSummary )

Use UpperCamelCase when naming classes: class ImportantClass. Use uppercase with underscores for global and class constants: DB_MASTER, Revision::REV_DELETED_TEXT. Other variables are usually lowercase or lowerCamelCase; avoid using underscores in variable names.

There are also some prefixes used in different places:

[edit] Functions

Verb phrases are preferred: use getReturnText() instead of returnText().

[edit] Variables

It is common to work with an instance of the Database 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; in development environments there is usually no difference between the two types, which can conceal subtle errors.

The following may be seen in old code but are discouraged in new code:

[edit] Documentation

[edit] Inline

The Doxygen documentation style is used (it is very similar to PHPDoc for the subset that we use). A code documentation example: giving a description of a function or method, the parameters it takes (using @param), and what the function returns (using @return), or the @ingroup or @author tags.

Use @ rather than \ as the escape character (i.e. use @param rather than \param) – both styles work in Doxygen, but only @param style works with PHPDoc. Use /** to begin the comments, instead of the Qt-style formating /*!.

General format for parameters is such: @param $varname [type] [description] (see the note in #Doxygen bugs affecting documentation):

/**
 * Get the text that needs to be saved in order to undo all revisions
 * between $undo and $undoafter. Revisions must belong to the same page,
 * must exist and must not be deleted
 * @param $undo Revision
 * @param $undoafter Revision Must be an earlier revision than $undo
 * @return mixed string on success, false on failure
 */
public function getUndoText( Revision $undo, Revision $undoafter = null ) {
        $undo_text = $undo->getText();
        $undoafter_text = $undoafter->getText();
        $cur_text = $this->getContent();
        if ( $cur_text == $undo_text ) {
                # No use doing a merge if it's just a straight revert.
         return $undoafter_text;
        }
        $undone_text = '';
        if ( !wfMerge( $undo_text, $undoafter_text, $cur_text, $undone_text ) ) {
                return false;
        }
        return $undone_text;
}

PHPDoc was used at the very beginning but got replaced with Doxygen for performance reason. We should probably drop PHPDoc compatibility.

There are a number of bugs in Doxygen that affect MediaWiki's documentation:

[edit] /docs folder

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.

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

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.

[edit] Messages

When creating a new 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.

HTML class and ID names should be prefixed with mw-. It seems most common to hyphenate them after that, like mw-some-new-class. Using the mw- prefix avoids conflicts with IDs generated by the wikitext parser to mark section headings.

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,

return wfMsg( 'templatesused-' . ( $section ? 'section' : 'page' ) ) )

is bad because a search for templatesused-section will not find this use of the message key. Instead do:

var key = section ? 'templatesused-section' : 'templatesused-page';
return mw.msg( key );

[edit] MySQL

Use UPPERCASE for MySQL keywords, and lowercase for things like types. Do not specify the lengths of numeric types, but do for varchar() and varbinary() types. Use varchar(14) for all timestamps, and parse them to the standard format using $dbw->timestamp( $ts ); do not use the timestamp field type.

Make sure to include the /*_*/ comment immediately before any table name; this will be replaced with the wiki's database prefix if necessary, and ommitting it will cause breakage. Similarly, include the /*$wgDBTableOptions*/ comment after any table declaration, and /*i*/ immediately before any index names.

Create indices as separate statements, do not include them in the table creation query; the separate syntax is clearer and makes it easier to see the difference between unique and non-unique indices. Don't create indices with ALTER TABLE ... ADD INDEX ..., always use CREATE INDEX ... ON ... instead.

--
-- Track page-to-page hyperlinks within the wiki.
--
CREATE TABLE /*_*/pagelinks (
  -- Key to the page_id of the page containing the link.
  pl_from int unsigned NOT NULL default 0,
 
  -- Key to page_namespace/page_title of the target page.
  -- The target page may or may not exist, and due to renames
  -- and deletions may refer to different page records as time
  -- goes by.
  pl_namespace int NOT NULL default 0,
  pl_title varchar(255) binary NOT NULL default ''
) /*$wgDBTableOptions*/;
 
CREATE UNIQUE INDEX /*i*/pl_from ON /*_*/pagelinks (pl_from,pl_namespace,pl_title);
CREATE UNIQUE INDEX /*i*/pl_namespace ON /*_*/pagelinks (pl_namespace,pl_title,pl_from);

[edit] Table naming

[edit] ResourceLoader

[edit] Module naming

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".

See also:

[edit] JavaScript

See also JavaScript performance

In most cases conventions for PHP can perfectly apply to JavaScript code. Following are JavaScript specific conventions.

If making use of a scope (ie. local variables), always wrap your code in a closure. This avoids leaking variables to, or being given local variables from, another module. Use one of the following constructions ("Immediately-Invoked Function Expression"[2]):

( function() { 
        // Simple closure.
        // Code here will be invoked immediately
} )();
 
( function( $ ) { 
        // Simple closure
        // Code here will be invoked immediately with jQuery as first argument ($)
} )( jQuery );
 
jQuery( document ).ready( function( $ ) { 
        // Function bound to document ready queue
        // This function will not be invoked immediately,
        // instead it is called by jQuery when the document is ready
 
        // jQuery( fn ), is a shortcut to jQuery( document ).ready( fn )
} );

[edit] jQuery

See also jQuery

jQuery is now provided as a standard library in MediaWiki 1.17; familiarize yourself with its API and don't be afraid to use jQuery for DOM manipulation, AJAX requests, and utility functions. These are usually much easier to work with than classic low-level DOM and DHTML interfaces, and much more consistent across browsers.

To avoid confusion with raw elements or other variables, we prefix variables storing instances of jQuery with a dollar symbol. This makes it easy to recognize and manipulate them even with great distance between point X and the point of definition. A common problem is when referring to them in an if statement. document.getElementById returns null if no element matched the ID, therefor (since null casts to boolean false) it can be used as-is in an if statement. jQuery objects on the other hand (as any object in JavaScript) cast to boolean true no matter what.

[edit] JavaScript naming

Naming of functions, variables, constructor functions etc. is pretty much the same as we do in PHP.

Use lowerCamelCase when naming functions or variables. For example:

Use UpperCamelCase when naming object constructors.

[edit] jQuery pitfalls

$( '#pagehistory li input[name=diff]' ); // Bad
$( '#pagehistory li input[name="diff"]' ); // Good!
 
$( '#foo' ).find( 'input[name=test[]]' ); // Very bad
$( '#foo' ).find( 'input[name="test[]"]' ); // Good!

[edit] JavaScript pitfalls

[edit] Best practices

[edit] Whitespace

[edit] Commenting and documentation

Document functions and variables (see #Documentation). Make sure though that you use the JavaScript terminology (ie. not bool but Boolean)

In older versions of MediaWiki, JavaScript code was often very poorly commented to keep it small. Since MediaWiki 1.17 and higher run code through ResourceLoader's minification helpers by default, please feel free to liberally comment your code to aid future maintainers.

Doxygen/jsdoc documentation is not yet built automatically from JavaScript files, but it may be at some point in the future. In the meantime, some advanced editors like NetBeans can make use of jsdoc-style annotations to aid in autocomplete and code navigation.

Here's the format we aim to follow from now on:

/**
 * Create an outsources Cool object.
 * @constructor
 *
 * @example
 *      new Cool( 5 );
 *
 * @param foo {Number} Total sources.
 */
function Cool( foo ) {
        // ...
}
 
/**
 * Some short description of this function.
 *
 * @example
 *      $( '.foo' ).foobar();
 *
 * @context {jQuery}
 * @return {String} HTML-fragment
 */
$.fn.foobar = function() {
        if ( this.val() == 'baz' ) {
                return this.html();
        }
        return this.html( '<baz>Foo foo foo</baz>' ).html();
}

[edit] CSS

.selector,
#someElement {
        float: right;
        text-align: left;
}

[edit] See also

  1. ↑ http://lists.wikimedia.org/pipermail/wikitech-l/2011-August/054839.html
  2. ↑ http://benalman.com/news/2010/11/immediately-invoked-function-expression/
Language: English  • Français • 日本語
Retrieved from "http://www.mediawiki.org/wiki/Manual:Coding_conventions"
Personal tools
Namespaces
Variants
Actions
Site
Support
Download
Development
Communication
Print/export
Toolbox