MobileFrontend code guidelines

codeGuidelines.markdown

Code guidelines

This document briefly describes guidelines for writing code for the MobileFrontend MediaWiki extension.

File names

• File names should use camelCase. In case of PHP files, the name should start with a capital letter and should be named after the main class they contain. Other files should be started with a lowercase letter.
• Do not use the mf- prefix.
• PHP test files should be suffixed with Test, JavaScript test files should be prefixed with test_. TODO: maybe also prefix JS files?
• Template and LESS/CSS files used only by a single class in JavaScript should be named after the class, e.g. TutorialOverlay.less.

JavaScript

Naming conventions

Standard MediaWiki naming conventions apply TODO: links

• Use camelCase for variable names and event names.
• Start constructor functions with capital letters.

Modules

Each JavaScript file can be a module, i.e. can expose some functionality to other JavaScript files.

• Wrap each module (in fact, every JavaScript file) in a closure.
• Use closure's arguments to alias mw.mobileFrontend and jQuery objects as M and $ respectively (but only if the module needs them):

( function( M, $ ) {
    // module contents
}( mw.mobileFrontend, jQuery ) );

• Expose module's functionality using M.define:

( function( M, $ ) {
    // module contents

    M.define( 'moduleName', {
        SomeConstructor: SomeConstructor,
        someFunction: someFunction
    } );
}( mw.mobileFrontend, jQuery ) );

• Module's name should be the same as module's file name (without the .js extension).
• Use other module's functionality using M.require:

( function( M, $ ) {
    var someFunction = M.require( 'moduleName' ).someFunction;

    // module contents
}( mw.mobileFrontend, jQuery ) );

jQuery

• Use jQuery.Deferred as a return value of asynchronous functions. Use #resolve/#done for success and #reject/#fail for errors.
• Use jQuery objects in favor of native DOM elements (for the sake of consistency).
• Avoid using $( document ).ready unless necessary. Most of the JavaScript files are loaded at the bottom of the page anyway.
• Avoid jQuery/HTML spaghetti code, instead use View and Hogan templates (same syntax as Mustache).

CSS/LESS

TODO: does mw have any conventions? link?

• Do not use the mw-mf- prefix.
• Use lowercase letters and a hyphen as the word separator in class and id names (search-box is good, searchBox is bad).

I tried not to break any rules from MW core. I think one that we're not following but might consider is:

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

Although I'm not sure if we want to.