Reading/Web/Coding conventions

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

Indenting
e.g. (function { var foo;
 * Always use tabs for indents.
 * Always indent - even inside JavaScript closures

Commit Messages
When committing make sure you clearly label the type of commit. This helps us build nice reader friendly deployment logs like this one.
 * Stories: These cards do not need any special treatment. It can help however to add the Trello permalink to the bottom but is not necessary.
 * Bug: Bugs should finish with "Bug: X" where X is the bug number in Bugzilla. There should be no whitespace underneath between this line and the change id so that it gets reported to Bugzilla.
 * Hygiene: When tidying up code e.g. refactoring, addressing FIXME's and there is no related bug number, provided the change doesn't (intentionally) break or fix any functionality prefix your commit with hygiene.
 * QA: Prefix with "QA:" for any patch which updates or builds on our acceptance/browser tests.
 * i18n: Any patch which fixes a localisation problem or updates localisation messages and that does not have a bug number should commence with 'i18n:'
 * Dependencies: When committing a patch with a dependency or dependencies, be sure to include "Dependency: ChangeId" where ChangeID is the change id of the commit that needs to be merged beforehand. When multiple dependencies exist be sure to list them on separate lines.

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. If a JavaScript file defines a constructor, then its name should also start with a capital letter. 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.

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
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 Resources.php, the module name should reflect the functionality it offers and where. For example, the name  describes a module containing styles that are only applied to the Special:MobileDiff page,   describes scripts that should only be applied to the Special:MobileDiff.

Try to group modules by their type:
 * modules related to special pages should start with
 * modules related to the Minerva skin used by MobileFrontend should start with
 * modules implementing a particular feature should start with a word describing it, e.g.

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

Naming functions

 * When returning true or false the function should be prefixed with 'is' or 'has' e.g. isBetaGroupMember, isLoggedIn etc.Functions should be camel cased.

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.

URL Routing (Use of the URL hash)
When navigating to a route always prefix it with '/' to distinguish it from element IDS

e.g. #/notifications not #notifications

File organisation
Always use camel case. Group related files in folders describing the functionality.

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

Use camelCase for variable names.

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

Start constructor functions with capital letters.

Use  as the name of the variable holding event data in event handlers.

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

A module has one of two purposes
 * 1) Provide reusable functionality via a class and the use of M.define: A module should only create one class and should use an uppercase character when naming the class e.g. Toast, Api, EditorOverlay. The module may also define an instance of itself via M.define - e.g. M.define( 'api' ) = new Api
 * 2) Execute some code providing some new functionality: This tends to use classes defined in other modules.

When writing modules be sure to 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).

If the only thing exposed by a module is a class/constructor function, then the module name (and file name) should be capitalized:

Use other module's functionality using :

jQuery
Use  rather than   when creating new DOM nodes (or even better, use templates).

Use  to bind events rather than other convenience functions such as click

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

Views
When dealing with JavaScript views, have a look at Mobile_web/Coding_conventions/JavaScript/Views, you will find information and good practices.

Events map
Instead of handling all events, used in a class, in functions like postRender and friends, we want to use our Events map in MobileFrontend's JavaScript classes. This map works as a central definition of used events. The advantage is, that we can easily see, what events are used and know where they're handled.

Usage: The events map is an object,that maps events and jQuery selectors to functions. Example: This example is the same as:

CSS/LESS
We currently use LESS to generate stylesheets. 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.

Colors
Reuse colors in variables.less file. Do not introduce new colours outside this variable file, especially when you work with the color gray.

Icons
Reuse the icon classes in icons.less When introducing a new icon, only put it in icons.less if the icon is widely used. If not, be sure that the class name that serves it is prepended with 'icon-'

Units
When using values less than 1 write without the leading 0 e.g. .5em not 0.5em, .37em not 0.37em

Use shorthand where possible
Where ever possible use the shorthand rule to reduce number of css rules. As a rule of thumb if you have a margin-left and a margin-top in the same rule you should probably be using margin. Use background rather than background-image where possible.

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.

QUnit
e.g. javascripts/modules/foo.js should have a test as tests/qunit/modules/test_foo.js e.g. QUnit.module( 'MobileFrontend modules/editor/EditorApi' )
 * All QUnit tests should be prefixed with 'test_'
 * Tests should mirror the directory structure of the thing they are testing
 * QUnit modules should be named after the JavaScript module they are testing and prefixed with MobileFrontend

PHPUnit

 * All PHPUnit tests should be suffixed with '_test'

Browser tests
Please look at the serious guidelines for writing browser tests.

Steps should be written in sentence case. e.g.


 * Given the user is stupid
 * When the user hits the button
 * Then I see the unicorn
 * And the unicorn pukes a rainbow at me
 * And William McKinley's ghost appears
 * And there is lightning

When a step has arguments wrap it in quotes e.g.
 * Given I enter username "Foo"
 * And I type my password
 * When I click submit
 * Then I see a toast message with the text "Welcome!"