View source for Manual:Coding conventions/JavaScript

<languages/>
{{Shortcut|CC/JS}}
{{Development guideline}}
{{TOC|align=right}}
<translate><!--T:196--> This page describes '''coding conventions''' for '''JavaScript''' in the [[<tvar name=1>Special:MyLanguage/Manual:Code</tvar>|MediaWiki codebase]].</translate>
<translate><!--T:197--> See also the [[<tvar name=1>Special:MyLanguage/Manual:Coding conventions#All languages</tvar>|general conventions]].</translate>

<translate>
== Linting == <!--T:198-->
</translate>
<translate><!--T:234--> We use [<tvar name=url>https://eslint.org/</tvar> ESLint] as our code quality tool, with the <tvar name=1>[https://github.com/wikimedia/eslint-config-wikimedia eslint-config-wikimedia]</tvar> preset to encode most of our coding style and code quality rules.</translate>
<translate><!--T:235--> Refer to [<tvar name=url>https://eslint.org/docs/latest/use/integrations</tvar> Integrations on eslint.org] for many text editors or IDEs with plugins to provide live feedback as you type.</translate>

<translate>
=== Linter configuration === <!--T:199-->
</translate>
<translate><!--T:240--> To exclude files or directories from the analysis (e.g. third-party libraries), you can [<tvar name=url>https://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories</tvar> configure ignore patterns] in ESLint, through an <tvar name=1><code>.eslintignore</code></tvar> file.</translate><ref>
<translate><!--T:437--> [[<tvar name=1>phab:T204176</tvar>|Decide which "eslint ignore" method to use]], April 2020.</translate>
</ref>
<translate><!--T:241--> Note that <tvar name=code><code>node_modules</code></tvar> is excluded by default, so most repos would not need to set up any ignore rules.</translate>

<translate><!--T:242--> Every repo needs an <tvar name=1><code>.eslintrc.json</code></tvar> file in the root directory of the repository.</translate>
<translate><!--T:243--> The following shows an example ESLint config file:</translate>

<syntaxhighlight lang="json">
{
	"root": true,
	"extends": [
		"wikimedia/client",
		"wikimedia/jquery",
		"wikimedia/mediawiki"
	],
	"globals": {
		// <translate nowrap><!--T:439--> Project-wide globals.</translate>
	},
	"rules": {
		// <translate nowrap><!--T:440--> Project-wide rule variations.</translate> <translate nowrap><!--T:441--> Keep to a minimum.</translate>
	}
}
</syntaxhighlight>

<translate>
<!--T:244-->
See [<tvar name=url>https://github.com/wikimedia/mediawiki-core/blob/master/.eslintrc.json</tvar> <tvar name=1>.eslintrc.json</tvar> in MediaWiki] and [<tvar name=url2>https://github.com/wikimedia/mediawiki-extensions-VisualEditor/blob/master/.eslintrc.json</tvar> VisualEditor] for live examples.

<!--T:245-->
Remember to set <tvar name=1><code>"root": true</code></tvar> to avoid unintended "magic inheritance" of ESLint configurations in unrelated parent directories that you or the CI server might have set up on the disk (for example between a MediaWiki extension and MediaWiki core, or between your project directory and something in your home directory).
</translate>

<translate><!--T:246--> The <tvar name=1>[https://github.com/wikimedia/eslint-config-wikimedia eslint-config-wikimedia]</tvar> preset provides several profiles that projects can choose from as they see fit, such as different language flavours, or run-time environments globals.</translate>
<translate><!--T:247--> For example:</translate>

* <code>wikimedia/client</code> – <translate><!--T:484--> for browser code in the current default ES environment (currently ES2016, so an alias of <tvar name=1><code>wikimedia/client/es2016</code></tvar>)</translate>
** <code>wikimedia/client/es5</code> – <translate><!--T:248--> for browser code that specifically expects ES5 support</translate>
** <code>wikimedia/client/es6</code> – <translate><!--T:249--> for browser code that specifically expects ES6 support</translate>
* <code>wikimedia/server</code> – <translate><!--T:250--> for <tvar name=1>Node.js</tvar> code with ES2018 support</translate>
* <code>wikimedia/qunit</code> – <translate><!--T:251--> a mixin for QUnit tests</translate>

<translate><!--T:252--> You should expect to use multiple <tvar name=1><code>.eslintrc.json</code></tvar> files in a repo to set different environmental expectations for different subdirectories.</translate>
<translate><!--T:253--> This makes sure that you don't accidentally use <tvar name=1><code>window</code></tvar> methods in server code you expect to run on the server, or reference QUnit in production code.</translate>
<translate><!--T:254--> <tvar name=1><code>.eslintrc.json</code></tvar> files in subdirectories automatically inherit from the parent directory's configuration, so they only need to contain the things that are specific to that directory ([<tvar name=url>https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.rcfilters/.eslintrc.json</tvar> example file]).</translate>

<translate>
=== Continuous integration === <!--T:200-->
</translate>
<translate><!--T:255--> Projects are encouraged to enforce ESLint passing by including it their <tvar name=1><code>npm test</code></tvar> script via the "test" command in <tvar name=2><code>package.json</code></tvar>.</translate>
<translate><!--T:256--> See <tvar name=link>[[Continuous integration/Entry points]]</tvar> for more information about that.</translate>

<translate>
<!--T:257-->
If your project has a fairly heavy test pipeline, one could define an <tvar name=1><code>npm run lint</code></tvar> or even <tvar name=2><code>npm run lint:js</code></tvar> script in <tvar name=3><code>package.json</code></tvar> to make it easy to run just those from the command-line during local development (so that one doesn't have to open each file in an editor and/or to wait for CI).
</translate>

<translate><!--T:258--> To expose other command-line features from ESLint (such as linting individual files outside a text editor, or using the [<tvar name=url>https://eslint.org/docs/user-guide/command-line-interface#fixing-problems</tvar> --fix] feature), define "eslint" as its own script in package.json without any argument.</translate>
<translate><!--T:259--> You can then invoke it from the command-line as follows:</translate>

<syntaxhighlight lang="bash">
# <translate nowrap><!--T:442--> Entire directory, recursive</translate>
$ npm run eslint -- .
$ npm run eslint -- resources/

# <translate nowrap><!--T:443--> Single file</translate>
$ npm run eslint -- resources/ext.foo/bar.js

# <translate nowrap><!--T:444--> Fixer</translate>
$ npm run eslint -- --fix resources/ext.foo/
</syntaxhighlight>

<translate>
== Whitespace == <!--T:201-->

=== Spaces === <!--T:202-->

<!--T:260-->
We use the following conventions:
</translate>

* <translate><!--T:261--> Indentation with tabs.</translate>
* <translate><!--T:262--> No trailing whitespace.</translate>
* <translate><!--T:263--> Use blank lines to separate one block of logically related code from another.</translate>
* <translate><!--T:264--> One space on both sides of binary operators and assignment operators.</translate>
* <translate><!--T:265--> Keywords followed by a "<tvar name=1><code>(</code></tvar>" (left parenthesis) must be separated by one space. This gives visual distinction between keywords and function invocations.</translate>
* <translate><!--T:266--> There should be no space between the function name and left parenthesis of an argument list.</translate>
* <translate><!--T:267--> There should be one space on the insides of parentheses (such as in if statements, function calls, and arguments lists).</translate>
* <translate><!--T:268--> Don't use operators as if they are functions (such as <tvar name=1><code>delete</code></tvar>, <tvar name=2><code>void</code></tvar>, <tvar name=3><code>typeof</code></tvar>, <tvar name=4><code>new</code></tvar>, <tvar name=5><code>return</code></tvar>, ..).</translate>

<translate>
<!--T:269-->
These and other aspects of our style guide are enforced with ESLint.
</translate>

{|
|+ <translate><!--T:270--> Space examples</translate>
! <translate><!--T:271--> Correct</translate>
! <translate><!--T:272--> Wrong</translate>
|-
| {{code convention example|posneg=positive|
<syntaxhighlight lang="javascript">
a.foo = bar + baz;

if ( foo ) {
	foo.bar = doBar();
}

function foo() {
	return bar;
}

foo = function () {
	return 'bar';
};

foo = typeof bar;

function baz( foo, bar ) {
	return 'gaz';
}

baz( 'banana', 'pear' );

foo = bar[ 0 ];
foo = bar[ baz ];
foo = [ bar, baz ];

</syntaxhighlight>
}}
| {{code convention example|posneg=negative|
<syntaxhighlight lang="javascript">
a.foo=bar+baz;

if( foo ){
	foo.bar = doBar () ;
}

function foo () {
	return bar;
};

foo = function() {
	return('bar');
};

foo = typeof( bar );

function baz(foo, bar) {
	return 'gaz';
}

baz('banana', 'pear');

foo = bar[0];
foo = bar[baz];
foo = [bar,baz];
</syntaxhighlight>
}}
|}

<translate>
=== Line length === <!--T:203-->
</translate>
<translate><!--T:273--> Lines should wrap at no more than 80–100 characters.</translate>
<translate><!--T:274--> If a statement does not fit on a single line, split the statement over multiple lines.</translate>
<translate><!--T:275--> The continuation of a statement should be indented one extra level.</translate>

<translate><!--T:276--> Function calls and objects should either be on a single line or split over multiple lines with one line for each segment.</translate>
<translate><!--T:277--> Avoid closing a function call or object at a different indentation than its opening.</translate>

{|
|+ <translate><!--T:278--> Line breaking examples</translate>
! <translate><!--T:279--> Yes</translate>
|-
|{{code convention example|posneg=positive|
<syntaxhighlight lang="javascript" line>
// <translate nowrap><!--T:445--> One line</translate>
if ( mw.foo.hasBar() && mw.foo.getThis() === 'that' ) {
	return { first: 'Who', second: 'What' };
} else {
	mw.foo( 'first', 'second' );
}

// <translate nowrap><!--T:446--> Multi-line (one component per line)</translate>
if (
	// <translate nowrap><!--T:447--> Condition head indented one level.</translate>
	mw.foo.hasBar() &&
	mw.foo.getThis() === 'that' &&
	!mw.foo.getThatFrom( 'this' )
) {
    // ↖ <translate nowrap><!--T:448--> Closing parenthesis at same level as opening.</translate>
	return {
		first: 'Who',
		second: 'What',
		third: 'I don\'t know'
	};
} else {
	mw.foo(
		[ 'first', 'nested', 'value' ],
		'second'
	);
}
</syntaxhighlight>
}}
|-
! <translate><!--T:280--> No</translate>
|-
|{{code convention example|posneg=negative|
<syntaxhighlight lang="javascript" line>
// <translate nowrap><!--T:449--> No: Mixed one line and multi-line</translate>
if ( mw.foo.hasBar() && mw.foo.getThis() === 'that' &&
	!mw.foo.getThatFrom( 'this' ) ) {

	// <translate nowrap><!--T:450--> No: varying number of segments per line.</translate>
	return { first: 'Who', second: 'What',
		third: 'I don\'t know' };

} else {
	mw.foo( 'first', 'second',
		'third' );

	// <translate nowrap><!--T:451--> No: Statements looking like they are split over multiple lines but still on line.</translate>
	// <translate nowrap><!--T:452--> Visualy looks like a call with one parameter, or with an array as first parameter.</translate>
	mw.foo(
		'first', 'second', 'third'
	);

	mw.foo(
		[ 'first', 'nested', 'value' ], 'second'
	);
}
</syntaxhighlight>
}}
|}

<translate>
== Structure == <!--T:204-->

<!--T:281-->
In a nutshell:
</translate>

<syntaxhighlight lang="javascript">
// <translate nowrap><!--T:453--> Variables that have literal and cheap initial values</translate>
const baz = 42;
const quux = 'apple';

// <translate nowrap><!--T:454--> Local functions</translate>
function local( x ) {
	return x * quux.length;
}

// <translate nowrap><!--T:455--> Main statements</translate>
const foo = local( baz );
const bar = baz + foo;
</syntaxhighlight>

<translate>
=== Closure === <!--T:205-->
</translate>
<translate><!--T:282--> If a module bundle can't or otherwise isn't yet registered using {{<tvar name=1>ll|ResourceLoader/Package files</tvar>|package files}}, then its individual JavaScript files should have a file-level closure around its code.</translate><ref>
<translate><!--T:283--> [[<tvar name="1">phab:T50886</tvar>|T50886: Remove obsolete file closures]], April 2019.</translate>
</ref>
<translate><!--T:284--> This gives the code its own scope, and avoids leakage of variables from or to other files, including in debug mode, and in a way that is understood by static analysis.</translate>
<translate><!--T:285--> This pattern is known as an [[w:Immediately-invoked function expression|immediately-invoked function expression]] (or "iffy").</translate><ref>
http://benalman.com/news/2010/11/immediately-invoked-function-expression/
</ref>

<translate><!--T:286--> For package files this is not needed, as they are executed as a "module" file rather than a "script" file, which naturally have their own local scope.</translate>
<translate><!--T:287--> ESLint should also be configured accordingly (set <tvar name="1"><code>"parserOptions": { "sourceType": "commonjs" }</code></tvar>, like in [<tvar name="url">https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.rcfilters/.eslintrc.json</tvar> this example]).</translate>

<translate>
=== Declarations === <!--T:206-->
</translate>
<translate><!--T:288--> Variables must be declared before use.</translate>
<translate><!--T:289--> Each assignment must be on its own line.</translate>
<translate><!--T:290--> Variables may be declared near or at their first assignment.</translate>

<syntaxhighlight lang="javascript">
const waldo = 42;
const quux = 'apple';

let foo, bar;
const flob = [ waldo ];
if ( isFound( waldo ) ) {
    foo = 1;
    bar = waldo * 2;
} else {
    foo = 0;
    bar = 0;
}

for ( let i = 0; i < flob.length; i++ ) {
    // ...
}
</syntaxhighlight>

<translate><!--T:293--> Functions should be declared before use.</translate>
<translate><!--T:294--> In the function body, function declarations should go after variable declarations and before any main statements.</translate>

<translate>
== Comments == <!--T:207-->

<!--T:295-->
Comments should be on their own line and go over the code they describe.
</translate>

<translate><!--T:296--> Within a comment, the opening syntax (e.g. slash-slash, or slash-star) should be separated from the text by a single space, and the text should start with a capital letter.</translate>
<translate><!--T:297--> If the comment is a valid sentence, then a full stop should be placed at the end of it.</translate>

<translate>
<!--T:308-->
Use line comments ({{<tvar name=1>tmpl|0=<code class="mw-highlight">{{#tag:span|// $1|class=c1}}</code></tvar>|foo}}) within functions and other code blocks (including for multi-line comments).
</translate>

<translate><!--T:312--> Use block comments ({{<tvar name="1">tmpl|0=<code class="mw-highlight">{{#tag:span|/* $1 */|class=cm}}</code></tvar>|foo}}) only for [[<tvar name=2>#Documentation</tvar>|documentation blocks]].</translate>
<translate><!--T:298--> This helps maintain consistent formatting for inline comments (e.g. not some as blocks and some as multi-line comments, or having to convert from one to the other).</translate>
<translate><!--T:299--> It also avoids confusing documentation engines.</translate>
<translate><!--T:300--> It also makes it easy to disable parts of the code during development by simply moving the end-comment notation a few lines down, without being short-circuited by an inline block comment.</translate>

<translate><!--T:301--> Be liberal with comments and don't fear file size because of it.</translate>
<translate><!--T:302--> All code is automatically minified by <tvar name=1>{{ll|ResourceLoader}}</tvar> before being shipped.</translate>

<translate>
=== Documentation comments === <!--T:208-->
</translate>
{{See also|Manual:Coding conventions/Documentation#Doc blocks}}
* <translate><!--T:303--> Text in free-form blocks should be sentence case (e.g. description of methods, parameters, return values etc.)</translate>
* <translate><!--T:304--> Start sentences with a capital letter.</translate>
* <translate><!--T:305--> Continue sentences belonging to an annotation on the next line, indented with one additional space.</translate>

<syntaxhighlight lang="javascript">
/**
 * <translate nowrap><!--T:456--> Get the user name.</translate>
 *
 * <translate nowrap><!--T:457--> Elaborate in an extra paragraph after the first one-line summary in the imperative mood.</translate>
 *
 * @param {string} <translate nowrap><!--T:459--> foo Description of a parameter that spans over on the next line of the comment.</translate>
 * @param {number} <translate nowrap><!--T:461--> bar</translate>
 * @return {string} <translate nowrap><!--T:462--> User name</translate>
 */
</syntaxhighlight>

<translate>
==== ES5 classes ==== <!--T:469-->

<!--T:470-->
To document a class that uses [[w:ECMAScript|ES5]] syntax, with the class and constructor defined together as <tvar name=1><code>function MyClass(…) {…}</code></tvar>, use:
</translate>

* <translate><!--T:471--> a <tvar name=1><code>@classdesc</code></tvar> tag to document the class</translate>
* <translate><!--T:472--> a <tvar name=1><code>@description</code></tvar> tag to document the constructor</translate>

<syntaxhighlight lang="javascript">
/**
 * @classdesc <translate nowrap><!--T:473--> Class description.</translate>
 *
 * @description <translate nowrap><!--T:474--> Constructor description.</translate>
 *
 * @param {string} <translate nowrap><!--T:475--> myParam</translate>
 * @return {string} <translate nowrap><!--T:476--> Description</translate>
 */
</syntaxhighlight>

<translate>
==== ES6 classes ==== <!--T:477-->

<!--T:478-->
To document a class that uses [[w:ECMAScript|ES6]] syntax, with the constructor defined using <tvar name=1><code>constructor()</code></tvar>, use separate comments to document the class and the constructor.
</translate>

<syntaxhighlight lang="javascript">
/**
 * <translate nowrap><!--T:479--> Class description.</translate>
 */
class myClass {
	/**
	 * <translate nowrap><!--T:480--> Constructor description.</translate>
	 *
     * @param {string} <translate nowrap><!--T:481--> myParam</translate>
     * @return {string} <translate nowrap><!--T:482--> Description</translate>
	 */
	constructor() {...}
}
</syntaxhighlight>

{{anchor|Documentation}}
<translate>
=== Generated documentation === <!--T:209-->
</translate>
{{tracked|T138401}}

<translate><!--T:313--> Use [<tvar name="url">https://jsdoc.app/</tvar> JSDoc] to build documentation (see <tvar name=1>[[wmdoc:|doc.wikimedia.org]]</tvar>).</translate>
<translate><!--T:483--> To set up and publish JSDoc documentation, see <tvar name=1>{{ll|JSDoc}}</tvar>.</translate>

<translate>
== Equality == <!--T:212-->
</translate>
* <translate><!--T:330--> Use strict equality operators (<tvar name="1"><code>===</code></tvar> and <tvar name="2"><code>!==</code></tvar>) instead of (loose) equality (<tvar name="3"><code>==</code></tvar> and <tvar name="4"><code>!=</code></tvar>).</translate> <translate><!--T:331--> The latter does type coercion.</translate>
* <translate><!--T:332--> No [[w:Yoda conditions|Yoda conditionals]].</translate>

<translate>
=== Type checks === <!--T:213-->
</translate>
* string: <code>typeof val === 'string'</code>
* number: <code>typeof val === 'number'</code>
* boolean: <code>typeof val === 'boolean'</code>
* Function: <code>typeof val === 'function'</code>
* object: <code>val === Object( val )</code><ref>Recommended instead of <code>typeof object === 'object'</code>, because <code>typeof null</code> is also <code>'object'</code>, and <code>typeof function () {}</code> is <code>'function'</code> instead of <code>'object'</code>. Recommended instead of <code>val instanceof Object</code>, because that's false for [https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects null-prototype objects] (<code>Object.create(null)</code>). To assert something is an object of any kind, the only reliable quick way is <code>val === Object( val )</code>.</ref>
* plain object: <code>[https://api.jquery.com/jQuery.isPlainObject/ jQuery.isPlainObject]( val )</code>
* array: <code>Array.isArray( val )</code>
* HTMLElement: <code>obj.nodeType === Node.ELEMENT_NODE</code>
* null: <code>val === null</code>
* undefined: <code>val === undefined</code>

<translate>
== Strings == <!--T:214-->
</translate>
<translate><!--T:337--> Use single quotes instead of double quotes for string literals.</translate>
<translate><!--T:338--> Remember there are no "magic quotes" in JavaScript ''i.e.'' <tvar name="1"><code>\n</code></tvar> and <tvar name="2"><code>\t</code></tvar> work everywhere.</translate>

<translate><!--T:339--> To extract part of a string, use the <tvar name="1"><code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/slice slice()]</code></tvar> method for consistency.</translate>
<translate><!--T:340--> Avoid the <tvar name="1"><code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/substr substr()]</code></tvar>, or <tvar name="2"><code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/substring substring()]</code></tvar> methods which are redundant, easily mistaken, and may have unexpected side effects.</translate><ref>
[https://timotijhof.net/posts/2020/substr-substring-slice/ <translate><!--T:341--> Should I <tvar name=1>substr()</tvar>, <tvar name=2>substring()</tvar>, or <tvar name=3>slice()</tvar>?</translate>]
</ref><ref>
<translate><!--T:342--> [<tvar name="url">https://masteringjs.io/tutorials/fundamentals/substring</tvar> Strings in JavaScript], Mastering JS.</translate>
</ref><ref>
[[gerrit:c/mediawiki/core/+/158108|Change 158108 - mediawiki/core]], {{ymd|2014|9|5}}, gerrit.wikimedia.org
</ref>

{{Anchor|Globals}}
<translate>
== Exporting == <!--T:215-->
</translate>
<translate><!--T:343--> Use globals exposed by the browser (such as <tvar name=1><code>document</code>, <code>navigator</code>, <code>URL</code>, <code>fetch</code></tvar>) directly and not as properties of the <tvar name=4><code>window</code></tvar> object.</translate>
<translate><!--T:344--> This improves confidence in code through static analysis and may also power other IDE features.</translate>
<translate><!--T:348--> In addition to browser globals, the only globals that are safe to use are <tvar name="1"><code>mw</code></tvar>, <tvar name=2><code>$</code></tvar> and <tvar name=3><code>{{ll|OOUI|OO}}</code></tvar>.</translate>

<translate><!--T:509--> Conversely, properties of <tvar name=1><code>window</code></tvar> (such as <tvar name=2><code>window.location</code>, <code>window.history</code>, <code>window.name</code></tvar>) should be accessed as properties of <tvar name=3><code>window</code></tvar>, not as bare globals, even though they are incidentally available as such.</translate>

<translate><!--T:345--> Avoid creating new global variables.</translate>
<translate><!--T:346--> Avoid modifying globals not "owned" by your code.</translate>
<translate><!--T:347--> For example, built-in globals such as String or Object must not be extended with additional utility methods, and similarly functionality relating to OOjs or jQuery should not be assigned to those globals.</translate>

<translate>
<!--T:352-->
To publicly expose functionality for re-use, use <tvar name="1"><code>module.exports</code></tvar> from {{<tvar name="2">ll|ResourceLoader/Package files</tvar>|Package files}}, and/or assign properties within the <tvar name="3"><code>mw</code></tvar> hierarchy, e.g. <tvar name=4><code>mw.echo.Foo</code></tvar>.

<!--T:349-->
Note that configuration variables exposed by MediaWiki must be accessed via <tvar name="1"><code>{{ll|Manual:Interface/JavaScript#mw.config|mw.config}}</code></tvar>.

=== Environment === <!--T:216-->
</translate>
<translate><!--T:350--> Modifying built-in protypes such as <tvar name="1"><code>Object.prototype</code></tvar> is considered harmful.</translate>
<translate><!--T:351--> This is not supported in MediaWiki code, and doing so will likely result in breakage of unrelated features.</translate>

<translate>
== Naming == <!--T:217-->

<!--T:355-->
All variables must be named using [[w:CamelCase|CamelCase]] starting with a lowercase letter, or use all caps (with underscores for separation) if the variable represents some kind of constant value.
</translate>

<translate><!--T:356--> All functions must be named using [[w:CamelCase|CamelCase]], generally starting with a lowercase letter unless the function is a class constructor, in which case it must start with an uppercase letter.</translate>
<translate><!--T:376--> Method functions are preferred to start with verb, e.g. <tvar name=1><code>getFoo()</code></tvar> instead of <tvar name=2><code>foo()</code></tvar>.</translate>

<translate>
=== Acronyms === <!--T:218-->
</translate>
<translate><!--T:357--> Names with acronyms in them should treat the acronym as a normal word and only uppercase the first letter as-needed.</translate>
<translate><!--T:358--> This applies to two-letter abbreviations as well, such as <tvar name="1"><code>Id</code></tvar>.</translate>
<translate><!--T:359--> For example, <tvar name="1"><code>getHtmlApiSource</code></tvar> as opposed to "<tvar name="2">getHTMLAPISource</tvar>".</translate>

<translate>
=== jQuery === <!--T:219-->
</translate>
<translate><!--T:360--> Distinguish DOM nodes from jQuery objects by prefixing variables with a dollar sign if they will hold a jQuery object, e.g. <tvar name="1"><code>$foo = $( '#bar' )</code></tvar>.</translate>
<translate><!--T:361--> This helps reduce mistakes where conditions use incorrect conditional checks, such as <tvar name="1"><code>if ( foo )</code></tvar> instead of <tvar name="2"><code>if ( $foo.length )</code></tvar>.</translate>
<translate><!--T:362--> Where DOM methods often return null (which is falsey), jQuery methods return an empty collection object (which, like native arrays and other objects in JavaScript, are truthly).</translate>

=== npm ===

<translate><!--T:364--> When publishing a standalone project to npmjs.org, consider publishing it under the <tvar name=1><code>@wikimedia</code></tvar> namespace.</translate>
<translate><!--T:363--> Note that some standalone projects, that are aimed at use outside the Wikimedia community and have a sufficiently unique name, currently use an unnamespaced package name (e.g. "<tvar name="1">oojs</tvar>" and "<tvar name="2">visualeditor</tvar>").</translate>
[[phab:T239742|T239742]]

<translate>
== Creating elements == <!--T:220-->

<!--T:233-->
To create a plain element, use the simple {{<tvar name=1>tag2</tvar>|tag}} syntax in the jQuery constructor:
</translate>

<syntaxhighlight lang="javascript">
$hello = $( '<div>' )
	.text( 'Hello' );
</syntaxhighlight>

<translate><!--T:365--> When creating elements based on the tag name from a variable (which may contain arbitrary HTML):</translate>

<syntaxhighlight lang="javascript">
// <translate nowrap><!--T:463--> Fetch 'span' or 'div' etc.</translate>
tag = randomTagName();
$who = $( document.createElement( tag ) );
</syntaxhighlight>

<translate>
<!--T:485-->
Only use <tvar name=1>{{jsi|1=$('<a title="valid HTML" href="#syntax">like this</a>');}}</tvar> when you need to parse HTML (as opposed to creating a plain element).

== Collections == <!--T:221-->
</translate>
<translate><!--T:366--> Different types of collections sometimes look similar but have different behaviour and should be treated as such.</translate>
<translate><!--T:367--> This confusion is mostly caused by the fact that arrays in JavaScript look a lot like arrays in other languages, but are in fact just an extension of Object.</translate>
<translate><!--T:368--> We use the following conventions:</translate>

{| class="wikitable plainlinks"
!  <translate><!--T:369--> Intent</translate>
!  <translate><!--T:370--> Arrays</translate>
!  <translate><!--T:371--> Plain Objects</translate>
! [https://api.jquery.com/jQuery/  <translate><!--T:377--> jQuery Objects</translate>]
|-
! <translate><!--T:378--> Declaration and empty initialisation</translate>
| {{jsi|1= x = [];}}
| {{jsi|1= x = {};}}
| {{jsi|1= $x = $( [] );}}
|-
!  <translate><!--T:372--> Access value</translate>
| {{jsi|x[ 0 ];}}
| {{jsi|x.key;}}
| <code>element = $x[ 0 ];</code><br /> or<br /><code>$y = $x[https://api.jquery.com/eq/ .eq]( 0 );</code>
|-
!  <translate><!--T:373--> Size</translate>
| {{jsi|x.length;}}
|<syntaxhighlight lang="javascript">
Object.keys( x ).length;
</syntaxhighlight>
| {{jsi|$x.length;}}
|-
!  <translate><!--T:374--> Iteration</translate>
| {{jsi|1= for ( i = 0; i < x.length; i++ ) {} }}<br />  or:<br /><code>x.forEach( ( value, i ) => {} );</code>
| {{jsi|for ( key in x ) {} }}
| <code>$x[https://api.jquery.com/each/ .each]( ( i, element ) => {} );</code>
|}

<translate>
<!--T:375-->
Avoid using a <tvar name=1><code>for-in</code></tvar> loop to iterate over an array (as opposed to a plain object), because <tvar name=1><code>for-in</code></tvar>  will result in many unexpected behaviours, including: keys as strings, unstable iteration order, indexes may skip gaps, iteration may include other non-numerical properties.

== Storage == <!--T:222-->

<!--T:381-->
Keys in localStorage and/or sessionStorage should be accessed via <tvar name=1><code>[[wmdoc:mediawiki-core/master/js/module-mediawiki.storage.html|mw.storage]]</code></tvar> or <tvar name=2><code>[[wmdoc:mediawiki-core/master/js/module-mediawiki.storage.html#.session|mw.storage.session]]</code></tvar>.

=== Keys === <!--T:223-->
</translate>
<translate><!--T:382--> Keys should start with <tvar name=1><code>mw</code></tvar> and use camel case and/or hyphens.</translate>
<translate><!--T:379--> Do not use underscores or other separators.</translate>
<translate><!--T:380--> Examples of real keys:</translate>

* <code>mwuser-sessionId</code>
* <code>mwedit-state-templatesUsed</code>
* <code>mwpreferences-prevTab</code>

<translate><!--T:385--> Beware that contrary to cookies via <tvar name=1>mw.cookie</tvar>, there is '''no wiki prefix''' or cookie prefix added by default.</translate>
<translate><!--T:383--> If values must vary by wiki, you must manually include <tvar name=1><code>{{ll|Manual:Interface/JavaScript#mw.config|wgCookiePrefix}}</code></tvar> as part of the key.</translate>

<translate>
=== Values === <!--T:224-->

<!--T:384-->
Values must be strings. Beware that attempting to store other value types will silently cast to a string (e.g. <tvar name=1>{{phpi|false}}</tvar> would become <tvar name=2>{{phpi|"false"}}</tvar>).
</translate>

<translate><!--T:386--> Space is limited.</translate>
<translate><!--T:387--> Use short and concise values over object structures where possible.</translate>
<translate><!--T:388--> A few example:</translate>

* <translate><!--T:389--> For boolean state (true/false, expanded/collapsed) use "1" or "0".</translate>
* <translate><!--T:390--> For values that are always numbers, store them as-is and cast with <tvar name=1><code>Number</code></tvar> on the way out (avoid <tvar name=2><code>parseInt</code></tvar>).</translate>
* <translate><!--T:391--> For values that are always strings, store them as-is.</translate>
* <translate><!--T:392--> For lists of software-defined values, consider comma-separated or pipe-separated strings to reduce space and processing cost.</translate>
* <translate><!--T:393--> For lists of values that may be user-generated or are otherwise complex in nature, use JSON.</translate>

<translate>
=== Eviction strategy === <!--T:225-->
</translate>
<translate><!--T:394--> Remember that Local storage does not have any eviction strategy by default.</translate>
<translate><!--T:395--> Therefore the following should be avoided:</translate>

* <translate><!--T:396--> Avoid using user-generated input as part of a key name.</translate>
* <translate><!--T:397--> Avoid keys containing identifiers for user-generated entities (e.g. user names, category names, page ids, or other user-provided or system-provided variables).</translate>
* <translate><!--T:398--> In general avoid approaches that involve creating a potentially large number of storage keys.</translate>

<translate><!--T:399--> For example, if a feature needs to store state about a variable entity (e.g. current page), it might make sense to use a single key for this feature as a whole and to limit the stored information only to the last few iterations (LRU).</translate>
<translate><!--T:400--> The slight increase in retrieval cost (the whole key, instead of separate smaller ones) is considered worth it, as otherwise the number of keys would grow uncontrollably.</translate>

<translate><!--T:401--> Even if the keys are not dependent on user-input, you may still want to use a single key for your feature because otherwise past versions of your software will have stored data that you can't clean up.</translate>
<translate><!--T:402--> By using a single key you can roundtrip it in a way that naturally doesn't persist unknown sub properties.</translate>

<translate><!--T:403--> Use of a tracking key is also an anti-pattern and does not avoid the above issues, as this would leak due to race conditions in HTML5 web storage being shared and non-atomic between multiple open browser tabs.</translate>

<translate><!--T:404--> When feature's use of Local storage is to be removed, be sure to implement an eviction strategy first to clean up old values.</translate>
<translate><!--T:405--> Typically <tvar name=1>[[wmdoc:mediawiki-core/master/js/mw.html#.requestIdleCallback|mw.requestIdleCallback]]</tvar> is used to gracefully look for the key and remove it.</translate>
<translate><!--T:406--> See <tvar name=1>[[phab:T121646|T121646]]</tvar> for a more scalable approach.</translate>

<translate>
=== Personal information === <!--T:226-->
</translate>
<translate><!--T:407--> Avoid storing personal information in Local storage as it remains when a user logs out or closes their browser.</translate>
<translate><!--T:408--> Use Session storage instead.</translate>
<translate><!--T:409--> See <tvar name=1>[[phab:T179752|T179752]]</tvar>.</translate>

<translate>
== Asynchronous code == <!--T:227-->

<!--T:410-->
Asynchronous code should follow, and be compatible with, the Promise standard.
</translate>

<translate><!--T:411--> When you define an asynchronous method for other code to call, you may internally construct the returned [[wikt:thenable|thenable]] object either using <tvar name=1>[https://api.jquery.com/jquery.deferred/ $.Deferred]</tvar> or native Promise.</translate>

<translate><!--T:413--> When you call an asynchronous method, use only standard Promise-compatible methods such as <tvar name=1><code>then()</code></tvar> and <tvar name=2><code>catch()</code></tvar>.</translate>
<translate><!--T:414--> Avoid using jQuery-specific methods like <tvar name=1><code>done()</code></tvar> or <tvar name=2><code>fail()</code></tvar>, which could stop working without warning if the method you are calling internally transitions from <tvar name=3>$.Deferred</tvar> to native Promise.</translate>

<translate><!--T:415--> Note that there are also subtle legacy behaviours in the <tvar name=1><code>done</code></tvar> and <tvar name=2><code>fail</code></tvar> callbacks.</translate>
<translate><!--T:416--> Pay close attention when migrating existing code from <tvar name=1><code>done()</code></tvar> to <tvar name=2><code>then()</code></tvar> as doing so may cause the code to stop working correctly.</translate>
<translate><!--T:417--> Specifically, the <tvar name=1><code>done</code></tvar> and <tvar name=2><code>fail</code></tvar> callbacks invoke your callback synchronously if the Deferred was already settled by the time you attach your callback.</translate>
<translate><!--T:418--> This means your callback may be invoked before the attaching statement is finished running.</translate>

<translate><!--T:419--> For example:</translate>

<syntaxhighlight lang="javascript">
function getSqrt( num ) { return $.Deferred().resolve( Math.sqrt( num ) ); }

console.log( "A" );
getSqrt( 49 ).done( ( val ) => {
    console.log( "C" ); // <translate nowrap><!--T:464--> can be A C B, or, A B C</translate>
} );
console.log( "B" );

console.log( "A" );
getSqrt( 49 ).then( ( val ) => {
    console.log( "C" ); // <translate nowrap><!--T:465--> always A B C</translate>
} );
console.log( "B" );

const y = getSqrt( 49 ).then( ( val ) => {
    console.log( y.state(), val ); // <translate nowrap><!--T:466--> "resolved", 7</translate>
} );
const x = getSqrt( 49 ).done( ( val ) => {
    console.log( x.state(), val ); // <translate nowrap><!--T:467--> Uncaught TypeError: x is undefined</translate>
} );
const z = getSqrt( 49 );
z.done( ( val ) => {
    console.log( x.state(), val ); // <translate nowrap><!--T:468--> "resolved", 7</translate>
} );
</syntaxhighlight>

== jQuery ==
<translate><!--T:486--> jQuery is still supported in MediaWiki and it is a useful tool, but it is slow and dated, and there are some functions and patterns to avoid.</translate>
<translate><!--T:508--> The following emit warnings or errors in <tvar name=1>eslint-config-wikimedia</tvar>.</translate>

* <translate><!--T:487--> Avoid functions in the jQuery library that are deprecated, since these will be removed from jQuery at some point or already have been.</translate> <translate><!--T:488--> Examples:</translate> <code>.addSelf</code>, <code>.bind</code>, <code>.unbind</code>, <code>.boxModel</code>, <code>.browser</code>, <code>.camelCase</code>, <code>.context</code>, <code>.delegate</code>, <code>.undelegate</code><ref>https://github.com/wikimedia/eslint-config-wikimedia/blob/91e9a0ba09bc77471d21c1e92d24fa190109a08e/jquery.json#L8</ref>
* <translate><!--T:489--> Avoid functions in the jQuery library that have ES5/ES6 equivalents.</translate> <translate><!--T:490--> The ES5/ES6 equivalents are faster.</translate> <translate><!--T:491--> Examples:</translate> <code>.each</code>, <code>.grep</code>, <code>.inArray</code>, <code>.map</code>, <code>.trim</code>, <code>.error</code>, <code>.extend</code>, <code>.noop</code>.<ref name=":0">https://github.com/wikimedia/eslint-config-wikimedia/blob/91e9a0ba09bc77471d21c1e92d24fa190109a08e/jquery.json#L11-L28</ref>
* <translate><!--T:492--> Avoid functions in the jQuery library that have CSS equivalents.</translate> <translate><!--T:493--> The CSS equivalents are faster.</translate> <translate><!--T:494--> Examples:</translate> <code>.animate</code>, <code>.stop</code>, <code>.finish</code>, <code>.fadeIn</code>, <code>.fadeOut</code>, <code>.fadeTo</code>, <code>.fadeToggle</code>, <code>.slideDown</code>, <code>.slideToggle</code>, <code>.slideUp</code><ref name=":0" />
* <translate><!--T:495--> Avoid using jQuery to search the entire DOM, for performance reasons and to avoid selecting incorrect elements by mistake.</translate> <translate><!--T:496--> Prefer hooks such as <tvar name=1><code>mw.hook( 'wikipage.content' ).add( ( $content ) => {</code></tvar>, which provides a <tvar name=2><code>$content</code></tvar> element.</translate> <translate><!--T:497--> You can call <tvar name=1><code>.find()</code></tvar> on it repeatedly.</translate> <translate><!--T:498--> When you create elements, store them in a variable, then retrieve them later using the variable or <tvar name=1><code>$variable.find()</code></tvar>.</translate> <translate><!--T:499--> If you need to, you can make exceptions to this from time to time using comments such as <tvar name=1><code>// eslint-disable-next-line no-jquery/no-global-selector</code></tvar>.</translate>
** <translate><!--T:500--> For example, avoid <tvar name=1><code>$( '#id' )</code></tvar> and <tvar name=2><code>$( '.complex > selector' )</code></tvar>.</translate><ref>https://github.com/wikimedia/eslint-plugin-no-jquery/blob/master/docs/rules/no-global-selector.md</ref>
** <translate><!--T:501--> Avoid <tvar name=1><code>.hasClass</code></tvar> and some uses of <tvar name=2><code>.toggleClass</code></tvar>.</translate><ref>https://github.com/wikimedia/eslint-plugin-no-jquery/blob/master/docs/rules/no-class-state.md</ref>
* <translate><!--T:502--> Avoid [<tvar name=url>https://github.com/jquery/sizzle/wiki#other-selectors-and-conventions</tvar> sizzle selectors], for performance reasons and because some sizzle syntax is already deprecated.</translate> <translate><!--T:503--> For example, avoid <tvar name=1><code>$( '#mw-specialmute-form input:checkbox' )</code></tvar> and <tvar name=2><code>$input.is( ':visible' )</code></tvar>.</translate>
* <translate><!--T:504--> Avoid <tvar name=1><code>.globalEval</code></tvar>.</translate>
* <translate><!--T:505--> Generate complex HTML using multiple jQuery functions instead of just a string in the <tvar name=1><code>$()</code></tvar> function.</translate> <translate><!--T:506--> For example, prefer <tvar name=1><code>$( '<nowiki><a>' ).attr( 'href', 'https://test.com'</nowiki> ).text( 'Test' )</code></tvar> to <tvar name=2><code>$( '<a href="https://test.com">Test</a>' )</code></tvar>.</translate> <translate><!--T:507--> The latter is prone to errors that linters cannot detect, and triggers jQuery's HTML parser, which is slow.</translate><ref>https://github.com/wikimedia/eslint-plugin-no-jquery/blob/master/docs/rules/no-parse-html-literal.md</ref>

<translate>
== Final notes == <!--T:228-->

=== Reuse ResourceLoader modules === <!--T:229-->
</translate>
<translate><!--T:420--> Don't reinvent the wheel.</translate>
<translate><!--T:421--> Much JavaScript functionality and MediaWiki-related utilities ship with MediaWiki core that are stable and you can (literally) depend on them.</translate>
<translate><!--T:422--> See <tvar name=1>{{ll|ResourceLoader/Core modules}}</tvar> before rolling your own code.</translate>

<translate>
=== Pitfalls === <!--T:230-->
</translate>
* <translate><!--T:423--> Be careful to preserve compatibility with left-to-right '''and right-to-left languages''' (i.e. <tvar name=1><code>float: right</code></tvar> or <tvar name=2><code>text-align: left</code></tvar>), especially when styling text containers.</translate> <translate><!--T:425--> Putting those declarations in CSS file will allow them to be automatically flipped for RTL-languages by <tvar name=1>{{ll|CSSJanus}}</tvar> in <tvar name=2>{{ll|ResourceLoader}}</tvar>.</translate>
* <translate><!--T:424--> Use <tvar name=1><code>[https://api.jquery.com/attr/ attr()]</code></tvar> and <tvar name=2><code>[https://api.jquery.com/prop/ prop()]</code></tvar> appropriately.</translate><br /> <translate><!--T:431--> Read more:</translate>
** [https://api.jquery.com/attr/ jQuery#attr, jQuery API]
** [https://javascript.info/tutorial/attributes-and-custom-properties <translate><!--T:432--> Attributes and custom properties</translate>]
* <translate><!--T:426--> Consistently [<tvar name=url>https://api.jquery.com/category/selectors/attribute-selectors/</tvar> quote attribute] selector values: <tvar name=1><code>[foo="bar"]</code></tvar> instead of <tvar name=2><code>[foo=bar]</code></tvar> (<tvar name=3>[https://bugs.jquery.com/ticket/8229 jqbug 8229]</tvar>).</translate>
* <translate><!--T:433--> As of jQuery 1.4 the jQuery constructor has a new feature that allows passing an object as second argument, like: <tvar name=1><syntaxhighlight lang=javascript inline>$( '<div>', { foo: 'bar', click: () => {}, css: { .. } } );</syntaxhighlight></tvar>.</translate> <translate><!--T:427--> Don't use this.</translate> <translate><!--T:428--> It makes code harder to follow, fails on attributes (such as 'size') that are also methods, and is unstable due to this mixing of jQuery methods with element attributes.</translate> <translate><!--T:429--> A future jQuery method or plugin called "<tvar name=1>title</tvar>" might convert an element into a heading, which means the title attribute can also no longer be set through this method.</translate> <translate><!--T:430--> Be explicit and call <tvar name=1><code>.attr()</code></tvar>, <tvar name=2><code>.prop()</code></tvar>, <tvar name=3><code>.on()</code></tvar> etc. directly.</translate>

<translate>
=== Use CSS for styling many elements === <!--T:231-->
</translate>
<translate><!--T:236--> Don't apply styling to lots of elements at once; this has poor performance.</translate>
<translate><!--T:237--> Instead use a common parent's class (or add one) and apply CSS in a <tvar name=1><code>.css</code></tvar> or <tvar name=2><code>[[LESS|.less]]</code></tvar> file.</translate>
<translate><!--T:238--> 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.</translate>
<translate><!--T:239--> Do not set CSS into inline "style" attributes, don't insert "style" elements from JS either.</translate>

<translate>
== References == <!--T:232-->
</translate>
* <translate><!--T:434--> [<tvar name=url>https://contribute.jquery.org/style-guide/js/</tvar> JavaScript Style Guide], Contribute to jQuery</translate>
* <translate><!--T:435--> [<tvar name=url>https://www.crockford.com/code.html</tvar> Code Conventions for JavaScript], Douglas Crockford</translate>
* <translate><!--T:436--> [<tvar name=url>https://www.youtube.com/watch?v=_EANG8ZZbRs</tvar> Programming Style & Your Brain], Douglas Crockford on YouTube</translate>

----
<references />

{{Conventions navigation}}

[[Category:JavaScript{{#translation:}}]]