Reading/Web/Coding conventions

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

PHP test files should be suffixed with, JavaScript test files should be prefixed with. 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..

Config variables
Global config variables set by MobileFrontend need to identify the extension in some way, by general MW convention.

Config variables should be camel cased and prefixed with $wgMF Examples:
 * $wgMFPhotoUploadEndpoint
 * $wgMobileFrontendLogo

Previously '$wgMobileFrontend' was used but was abandoned in favor of '$wgMF...' because of brevity.

ResourceLoaderModules
Note this is a WIP and the spec is not finalised but the current suggested naming convention is as follows:

When naming a ResourceLoader module in wgResourceLoaderModules the module name should reflect the functionality it offers and where:

The name "mobile.special.mobilediff.styles" describes a module containing styles that are only applied to the Special:MobileDiff page, "mobile.special.mobilediff.scripts" describes scripts that should only be applied to the Special:MobileDiff.

For more common modules that can be used anywhere just use the mobile prefix.

"mobile.uploads" describes features adding uploads on mobile.

There is no need include 'beta' or 'alpha' in the module name. Please use comments instead to describe where those features reside.

Please deprecate the use of mobile.stable, mobile.beta and mobile.alpha

ResourceLoader modules
When naming classes try to avoid the MF prefix and instead try and describe what it does differently from a normal ResourceLoader module

Examples:
 * MobileSiteModule
 * MobileDeviceDetectModule.php

All classes should be written on the basis that one day they might make it into the desktop site. Note: MFResourceLoaderModule needs renaming - it pre-parses messages and provides template rendering.

File organisation
All classes no matter how small should be in a separate file. This helps with making classes easier to find within the codebase. All files should live in the includes folder (with the exception of global PHP files such as MobileFrontend.php). Remember not every one uses the same IDE as you!

Filenames should be mapped to class names. Burying multiple classes in a file, even if they're small classes, makes discovery a little more difficult for users with basic IDEs. We should encourage discovery of our code to newbies who are not familiar with the codebase.


 * api: Anything related to api goes here
 * modules: Put ResourceLoader module classes here
 * skins: Put skins here
 * specials: put SpecialPage modules here

i18n messages
If your message contains a single quote/apostrophe, wrap the entire message in double quotes rather than escaping the single quote.

Variables

 * Use ev in event handlers to represent events
 * Use TitleCamelCase for reusable 'classes' that can be instantiated
 * Use lowerCamelCase for instances of variables
 * $jQueryVariables should begin with a $ e.g. $div = $( ' ' )
 * $( ' ' ) instead of $( '  ' ) or $( '  ' )

Naming conventions
Standard MediaWiki naming conventions apply. Any JavaScript must pass the Manual:Coding_conventions/JavaScript.

Use camelCase for variable names and event names.

When naming events use lowercase letters and a hyphen as the word separator ( is good,   is bad).

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  and   objects as  and   respectively (but only if the module needs them):

Expose module's functionality using :

Module's name should be the same as module's file name (without the extension).

Use other module's functionality using :

jQuery
Use  as a return value of asynchronous functions. Use / for success and  /  for errors.

Use jQuery objects in favor of native DOM elements (for the sake of consistency).

Avoid using  unless necessary. Most of the JavaScript files are loaded at the bottom of the page anyway.

Avoid jQuery/HTML spaghetti code, instead use  and Hogan templates (same syntax as Mustache).

CSS/LESS
We currently use LESS to generate stylesheets. Ensure when you contribute CSS code you update the less files in stylesheets/less and to generate run:

make less

You need Node.js for the LESS compiler to run.

Ensure all CSS passes the Manual:Coding_conventions/CSS.

Do not use the  prefix.

Use lowercase letters and a hyphen as the word separator in class and id names ( is good,   is bad).

Avoid using attribute selectors - these are known to cause issues in the phonegap app which shares some of this codebase.

HTML
HTML should validate via W3C validator. Note, at the current time do not worry about markup introduced via wikitext and the 1 validation error that occurs due to MediaWiki core.