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

Do we need to use the test_ prefix on tests? I actually quite like the same filenames but in the test folder.. Also see https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/MobileFrontend.git;a=blob;f=README.mediawiki;h=3e49d1c1680306a3f5c938d1b7577ec8db28d906;hb=HEAD

We should either merge those two documents, or possibly extract the current guidelines parts from README.

I'd say that a test (we can remove the underscore) prefix/suffix is a common pattern and often makes it easier to open the right file quickly. If I have two tabs with name watchstart.js I have no way of knowing which one is a test and which one is implementation. My current Vim config works well with any naming, because I don't use tabs, but I know many people do in their editors (don't you have this problem in TextMate?). It's also common in the PHP part of our codebase.

But if you have a strong preference against this prefix/suffix we can get rid of it.

I've noticed non-global variables in some places starting with the 'wg' prefix. We should add a note to this mentioning that 'wg' is used as a prefix for global variables in mediawiki and generally map specifically to global config variables. Other vars should NOT use this convention.

Also, I haven't done a comparison yet, but I think we should approach our coding conventions as addendums to the MW-specific coding conventions for PHP and JS:
http://www.mediawiki.org/wiki/Coding_conventions
Let's be careful about introducing conventions that go against MW-wide conventions and avoid them if possible. If we need to go against existing convention, let's please provide sound justification for doing so.

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.