Manual:Coding conventions/JavaScript


 * See also JavaScript performance

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

Code structure
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" ):

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  statement. returns null if no element matched the ID, therefore (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.

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.

jQuery pitfalls

 * As recorded under jqbug 8229, the attribute selector values should always be quoted.


 * jQuery.fn is the same number of characters as , using   saves function call overhead (view source of .size). Remember to always use strict equals when comparing the .length attribute as 0 and 1 can cast to booleans.

JavaScript pitfalls

 * Do not assume the existence of any global variables other than  and  .   should always be aliased locally (see below).
 * Array-like access on a string doesn't work in older versions of IE such as IE6. Use the String method   instead.
 * Be sure to check the MDN Docs before using a prototype. The filter prototype for Arrays, for example, isn't supported in any version of Internet Explorer before 9. See also Compatibility.
 * Always define variables with a clear statement on whether they are local or global ( or  ). Especially since ResourceLoader combines several scripts into one file, wrapped in a self-executing anonymous function. Never make an assumption or imply its scope. Undeclared variables are assumed to be global - the opposite of PHP.
 * When throwing exceptions, use  rather than  . You can throw a string directly in JavaScript, but some debuggers won't pick up a stack trace or the location of the error without using the   constructor.
 * Checking for s or  s should be done through  and  at all times to cover for edge cases and cross-browser differences.
 * Be careful to preserve compatibility with left-to-right and right-to-left languages (ie.  or  ), especially when styling text containers. This is another reason why such declarations should be in css files, so that they are automagically flipped by ResourceLoader in RTL-languages.
 * When using an object literal, don't include a trailing comma.  will fail in some versions of IE while   will work universally.
 * Similarly, when using an array literal, don't include any extra commas. In older versions of IE,  will be interpreted as   instead of the expected.
 * Be sure to use or  the right way.  See also http://javascript.info/tutorial/attributes-and-custom-properties.

Best practices
Uncheck everything, except these: [x] Require curly braces around all blocks; [x] Don't check line breaks; [x] Browser
 * Don't apply styling to lots of elements at once; this has poor performance. Instead use a common parent's class (or add one) and apply CSS in a .css file. Thanks to ResourceLoader, this will all be loaded in the same HTTP request, so there's no performance penalty for having a separate CSS file. Do not set CSS into inline "style" attributes, don't insert "style" elements from JS either.
 * Use dot-notation whenever possible to access object members. ( instead of  )
 * Validate with JSHint as much as possible. Recommended JSHint settings:
 * Use array and object literal notation, do not use  or.
 * ,,   and the like do not create new contexts, avoid declaring variables inside them. Instead declare them outside and if needed (re)define them inside.
 * Don't use multiple  statements, combine them when possible and indent with a tab.
 * Be careful when validating the type of a variable. For example Array.isArray is not natively supported yet in all browsers, for details see jQuery's guideline page: http://docs.jquery.com/JQuery_Core_Style_Guidelines#Type_Checks.

Whitespace

 * Like CSS declarations, in an object literal the notation should have no space before the colon and one space after the colon.
 * Use operators such as typeof like, not like a function.

Commenting and documentation
Document functions and variables (see ). Make sure though that you use the JavaScript terminology (ie. not  but  )

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: