View source for Manual:Coding conventions/JavaScript/fr

<languages/>
{{Shortcut|CC/JS}}
{{Development guideline}}
{{TOC|align=right|limit=2}}
Cette page décrit les '''conventions de codage''' pour '''JavaScript''' dans la [[Special:MyLanguage/Manual:Code|base de code MediaWiki]].
Voir aussi les [[Special:MyLanguage/Manual:Coding conventions#All languages|conventions générales]].

== Linting ==
Nous utilisons [https://eslint.org/ ESLint] comme outil de qualité du code, avec le préréglage [https://github.com/wikimedia/eslint-config-wikimedia eslint-config-wikimedia] pour encoder la plupart de nos règles de style de codage et de qualité du code.
Reportez-vous à [https://eslint.org/docs/latest/use/integrations Intégrations sur eslint.org] pour trouver de nombreux éditeurs de texte ou IDE dotés de modules permettant de fournir un retour en direct pendant la saisie.

<span id="Linter_configuration"></span>
=== Configuration de Linter ===
Pour exclure des fichiers ou des répertoires de l'analyse (par exemple des bibliothèques tierces), vous pouvez [https://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories configurer les modèles à ignorer] dans ESLint, via un fichier <code>.eslintignore</code>.<ref>
[[phab:T204176|Décider de la méthode ''eslint ignore'' à utiliser]], avril 2020.
</ref>
Notez que <code>node_modules</code> est exclu par défaut, donc la plupart des dépôts n'ont pas besoin de mettre en place des règles d'ignorance.

Chaque dépôt a besoin d'un fichier <code>.eslintrc.json</code> dans le répertoire racine du dépôt.
L'exemple suivant montre un fichier de configuration ESLint :

<syntaxhighlight lang="json">
{
	"root": true,
	"extends": [
		"wikimedia/client-es5",
		"wikimedia/jquery",
		"wikimedia/mediawiki"
	],
	"globals": {
		// variables globales de niveau projet
	},
	"rules": {
		// variantes des règles de niveau projet. A réduire au maximum.
	}
}
</syntaxhighlight>

Voir [https://github.com/wikimedia/mediawiki-core/blob/master/.eslintrc.json .eslintrc.json dans MediaWiki] et l'[https://github.com/wikimedia/mediawiki-extensions-VisualEditor/blob/master/.eslintrc.json ÉditeurVisuel] pour des exemples concrets.

N'oubliez pas de définir <code>"root": true</code> pour éviter un "héritage magique" involontaire des configurations d'eslint dans des répertoires parents non liés que vous ou le serveur CI pourriez avoir mis en place sur le disque (par exemple entre une extension MediaWiki et le noyau MediaWiki, ou entre votre répertoire de projet et quelque chose de votre répertoire personnel).

La préselection [https://github.com/wikimedia/eslint-config-wikimedia eslint-config-wikimedia] fournit différents profils que les projets peuvent choisir à leur convenance, tel que les différentes langues, ou les varables d'environnement globales à l'exécution.
Par exemple :

* <code>wikimedia/client-es5</code> - pour le code du navigateur et prévoit un support ES5
* <code>wikimedia/client-es6</code> - pour le code du navigateur qui utilise ES6
* <code>wikimedia/server</code> - pour le code Node.js 10+ et prévoit un support ES2018
* <code>wikimedia/qunit</code> - un mixin pour les tests QUnit

Vous devez vous attendre à utiliser plusieurs fichiers <code>.eslintrc.json</code> dans un répertoire pour définir différentes attentes environnementales pour différents sous-répertoires.
Cela permet de s'assurer que vous n'utilisez pas accidentellement les méthodes <code>window</code> dans le code serveur que vous pensez exécuter sur le serveur ou que vous ne faites pas référence à QUnit dans le code de production.
Les fichiers <code>.eslintrc.json</code> des sous-répertoires héritent automatiquement de la configuration du répertoire de leur parents, donc ils ne doivent contenir que les éléments spécifiques à leur dossier ([https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.rcfilters/.eslintrc.json fichier exemple]).

<span id="Continuous_integration"></span>
=== Intégration continue ===
Nous encourageons les projets à forcer le passage de ESLint en l'incluant dans leur script <code>npm test</code> via la commande ''test'' dans <code>package.json</code>.
Voir [[Continuous integration/Entry points]] pour plus d'informations à ce sujet.

Si votre projet possède une chaîne de test conséquente, vous pouvez définir un script <code>npm run lint</code> ou même <code>npm run lint:js</code> dans <code>package.json</code> pour faciliter l'exécution de ceux que vous pouvez lancer à partir de la ligne de commande pendant le développement local (de sorte à ne pas avoir à ouvrir chaque fichier dans l'éditeur et / ou attendre le CI).

Pour exposer les autres fonctionnalités du mode ligne de commande de ESLint (comme la possibilité de passer ''lint'' sur des fichiers individuels hors éditeur de texte, ou d'utiliser [https://eslint.org/docs/user-guide/command-line-interface#fixing-problems --fix]), déclarez ''eslint'' par son propre script dans ''package.json'' sans argument.
Vous pouvez ensuite l'invoquer à partir de la ligne de commande comme suit :

<syntaxhighlight lang="bash">
# le répertoire complet, récursif
$ npm run eslint -- .
$ npm run eslint -- resources/

# fichier unique
$ npm run eslint -- resources/ext.foo/bar.js

# correctif
$ npm run eslint -- --fix resources/ext.foo/
</syntaxhighlight>

<span id="Whitespace"></span>
== Espace blanc ==

<span id="Spaces"></span>
=== Espaces ===

Nous utilisons les conventions suivantes :

* Indentation avec tabulations.
* Pas d'espace à la fin des lignes.
* Utilisez des lignes vides pour séparer des  blocs de code indépendants.
* Un espace de chaque côté des opérateurs binaires et des opérateurs d'affectation.
* Les mots-clés suivis d'une "<code>(</code>" (parenthèse gauche) doivent être séparés par un espace. Cela permet de distinguer visuellement les mots-clés des appels de fonction.
* Il ne doit pas y avoir d'espace entre le nom de la fonction et la parenthèse gauche d'une liste d'arguments.
* Il doit y avoir un espace à l'intérieur des parenthèses (comme dans les instructions if, les appels de fonction et les listes d'arguments).
* N'utilisez pas les opérateurs comme s'il s'agissait de fonctions (par exemple <code>delete</code>, <code>void</code>, <code>typeof</code>, <code>new</code>, <code>return</code>...).

Ces aspects et d'autres de notre guide de style sont appliqués avec ESLint.

{|
|+ Exemples d'espaces
! Correct
! Incorrect
|-
| {{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>
}}
|}

<span id="Line_length"></span>
=== Longueur de ligne ===
Les lignes ne doivent pas comporter plus de 80 à 100 caractères.
Si une déclaration ne tient pas sur une seule ligne, répartissez-la sur plusieurs lignes.
La suite d'une déclaration doit être indentée d'un niveau supplémentaire.

Les appels de fonction et les objets doivent être soit sur une seule ligne, soit répartis sur plusieurs lignes, avec une ligne pour chaque fragment.
Évitez de fermer un appel de fonction ou un objet à un niveau d'indentation différent de celui de son ouverture.

{|
|+ Exemples de saut de ligne
! Oui
|-
|{{code convention example|posneg=positive|
<syntaxhighlight lang="javascript" line>
// une ligne
if ( mw.foo.hasBar() && mw.foo.getThis() === 'that' ) {
	return { first: 'Who', second: 'What' };
} else {
	mw.foo( 'first', 'second' );
}

// plusieurs lignes (un composant par ligne)
if (
	// début de la condition indenté d'un niveau
	mw.foo.hasBar() &&
	mw.foo.getThis() === 'that' &&
	!mw.foo.getThatFrom( 'this' )
) {
    // ↖ parenthèse fermante au même niveau que la parenthèse ouvrante.
	return {
		first: 'Who',
		second: 'What',
		third: 'I don\'t know'
	};
} else {
	mw.foo(
		[ 'first', 'nested', 'value' ],
		'second'
	);
}
</syntaxhighlight>
}}
|-
! Non
|-
|{{code convention example|posneg=negative|
<syntaxhighlight lang="javascript" line>
// mauvais : mélange d'une ligne seule et de plusieurs
if ( mw.foo.hasBar() && mw.foo.getThis() === 'that' &&
	!mw.foo.getThatFrom( 'this' ) ) {

	// mauvais : nombre variable de segments par ligne.
	return { first: 'Who', second: 'What',
		third: 'I don\'t know' };

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

	// mauvais : les déclarations semblent être divisées sur plusieurs lignes mais c'est toujours la même.
	// ressemble visuellement à un appel avec un paramètre, ou avec un tableau comme premier paramètre.
	mw.foo(
		'first', 'second', 'third'
	);

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

== Structure ==

En résumé :

<syntaxhighlight lang="javascript">
// variables ayant des valeurs initiales littérales et simples
var baz = 42;
var quux = 'apple';

// fonctions locales
function local( x ) {
	return x * quux.length;
}

// déclarations principales
var foo = local( baz );
var bar = baz + foo;
</syntaxhighlight>

<span id="Closure"></span>
=== Fermeture ===
Si l'archive d'un module ne peut pas être enregistrée - ou ne l'est pas encore -  en utilisant les {{ll|ResourceLoader/Package files|fichiers de paquet}}, alors chacun de ses fichiers JavaScript doit individuellement avoir son code inclus dans une ''closure'' globale de niveau fichier.<ref>
[[phab:T50886|T50886: suppression des ''closure'' obsolètes dans les fichiers]], avril  2019.
</ref>
Ceci donne au code sa propre visibilité et évite la fuite des variables des autres fichiers même en mode debug, et cela d'une manière compréhensible par l'analyse statique.
Ce modèle est appellé ''expression de fonction appelée immédiatement'' ([[w:Immediately-invoked function expression|immediately-invoked function expression]] &mdash; iffy).<ref>
http://benalman.com/news/2010/11/immediately-invoked-function-expression/
</ref>

Pour les fichiers de paquets, cela n'est pas nécessaire, car ils sont exécutés comme un fichier de ''module'' plutôt qu'un fichier de ''script'', qui ont naturellement leur propre domaine local de visibilité.
ESLint doit également être configuré en conséquence (définir <code>"no-implicit-globals": "off"</code>, comme dans [https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.rcfilters/.eslintrc.json cet exemple]).

<span id="Declarations"></span>
=== Déclarations ===
Les variables doivent être déclarées avant leur utilisation.
Chaque affectation doit être sur une ligne séparée.
Les variables peuvent être déclarées à proximité ou lors de leur première affectation.

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

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

for ( var i = 0; i < flob.length; i++ ) {
    // ...
}
</syntaxhighlight>
Si vous combinez plusieurs assignations <code>var</code> dans une instruction, les déclarations qui n'attribuent pas de valeur doivent être regroupées avant les assignations.
Les lignes qui suivent doivent être indentées à un autre niveau.
<syntaxhighlight lang="javascript">
var $content,
	$wrapper = $( '<div>' ),
	$button = $( '<a>' )
		.attr( 'href', '#' )
		.text( 'Test' );
</syntaxhighlight>

Les fonctions doivent être déclarées avant leur utilisation.
Dans le corps de la fonction, les déclarations de la fonction doivent suivre la déclarations des variables et précéder les instructions principales.

<span id="Comments"></span>
== Commentaires ==

Les commentaires doivent avoir leur propre ligne et précéder le code qu'ils décrivent.

Dans un commentaire, la syntaxe d'ouverture (par exemple, la double barre oblique <code>//</code> ou la barre oblique suivie d'une étoile <code>/*</code>) doit être séparée du texte par un seul espace, et le texte doit commencer par une lettre majuscule.
Si le commentaire est une phrase valide, il convient de mettre le caractère de fin.

Utiliser les lignes de commentaire  ({{tmpl|0=<code class="mw-highlight">{{#tag:span|// $1|class=c1}}</code>|foo}}) dans les fonctions et les autres blocs de code (y compris pour les commentaires sur plusieurs lignes).

Utiliser les blocs de commentaire ({{tmpl|0=<code class="mw-highlight">{{#tag:span|/* $1 */|class=cm}}</code>|foo}}) uniquement pour [[#Documentation|documenter les blocs]].
Cela permet de maintenir cohérent le formatage des commentaires en ligne (par exemple, certains ne sont pas présentés sous forme de bloc et d'autres sont des commentaires multilignes, ou devant être convertis de l'un vers l'autre).
Il évite également de perturber les moteurs de documentation.
Il permet également de désactiver facilement des parties du code pendant le développement en déplaçant simplement la notation du commentaire final quelques lignes en bas, sans être interrompu par un commentaire de bloc en ligne.

Soyez généreux avec les commentaires et n'ayez pas peur de leur longueur quant à la taille du fichier.
Tout le code est automatiquement réduit par {{ll|ResourceLoader}} avant d'être utilisé.

<span id="Documentation_comments"></span>
=== Commentaires de documentation ===
{{See also|Manual:Coding conventions/Documentation#Doc blocks}}
* Le texte des blocs sous forme libre doit être sous forme de phrase (par exemple la description des méthodes, des paramètres, des valeurs de retour, etc.)
* Commencez les phrases par une lettre majuscule.
* Continuez les phrases appartenant à une annotation sur la ligne suivante, indentée par une espace supplémentaire.

<syntaxhighlight lang="javascript">
/**
 * Obtenir le nom d'utilisateur
 *
 * Créer dans un paragraphe supplémentaire après le premier résumé d'une ligne en
 * mode impératif.
 *
 * @param {string} foo Description d'un paramètre qui s'étend sur la
 *  ligne suivante de commentaire
 * @param {number} bar
 * @return {string} Nom d'utilisateur
 */
</syntaxhighlight>

<span id="ES5_classes"></span>
==== Classes ES5 ====

Pour documenter une classe qui utilise la syntaxe [[w:ECMAScript|ES5]] , avec la classe et le constructeur définis ensemble par <code>function MyClass(…) {…}</code>, utiliser :

* une balise <code>@classdesc</code> pour documenter la classe
* une balise <code>@description</code> pour documenter le constructeur

<syntaxhighlight lang="javascript">
/**
 * @classdesc Description de la classe.
 *
 * @description Description du constructeur.
 *
 * @param {string} monParamètre
 * @return {string} Description
 */
</syntaxhighlight>

<span id="ES6_classes"></span>
==== Classes ES6 ====

Pour documenter une classe qui utilise la syntaxe [[w:ECMAScript|ES6]] avec le constructeur défini par <code>constructor()</code>, utiliser des commentaires séparés pour documenter la classe et le constructeur.

<syntaxhighlight lang="javascript">
/**
 * Description de la classe.
 */
class myClass {
	/**
	 * Description du constructeur.
	 *
     * @param {string} monParamètre
     * @return {string} Description
	 */
	constructor() {...}
}
</syntaxhighlight>

{{anchor|Documentation}}
<span id="Generated_documentation"></span>
=== Documentation générée ===
{{tracked|T138401}}

Utiliser [https://jsdoc.app/ JSDock] pour générer la documentation (voir https://doc.wikimedia.org).
Pour configurer et publier la documentation JSDoc, voir {{ll|JSDoc}}.

<span id="Equality"></span>
== Égalité ==
* Utiliser les opérateurs d'égalité stricte (<code>===</code> et <code>!==</code>) au lieu des opérateurs d'égalité (large) <code>==</code> et <code>!=</code>. Ces derniers réalisent la coercition des types.
* N'utilisez pas les [[w:fr:Yoda conditions|conditions Yoda]].

<span id="Type_checks"></span>
=== Contrôles de type ===
* string: <code>typeof val === 'string'</code>
* number: <code>typeof val === 'number'</code>
* boolean: <code>typeof val === 'boolean'</code>
* Function: <code>typeof val === 'function'</code>
* null: <code>val === null</code>
* object: <code>val === Object( val )</code>
* 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>
* undefined:
** Variables locales : <code>variable === undefined</code>
** Propriétés : <code>obj.prop === undefined</code>
** Variables globales : <code>typeof variable === 'undefined'</code>

<span id="Strings"></span>
== Chaînes ==
Utiliser des guillemets simples au lieu de guillemets doubles pour les chaînes de caractères.
Rappelez-vous qu'il n'y a pas de guillemets magiques en JavaScript, par exemple <code>\n</code> et <code>\t</code> fonctionnent partout.

Pour extraire un morceau d'une chaîne de caractères, utiliser la méthode <code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/slice slice()]</code> pour la cohérence.
Évitez les méthodes <code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/substr substr()]</code> et <code>[https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/substring substring()]</code> qui sont redondantes, faciles à confondre et peuvent avoir des effets secondaires inattendus.<ref>
[https://timotijhof.net/posts/2020/substr-substring-slice/ Utiliser substr(), substring(), ou slice() ?], timotijhof.net.
</ref><ref>
[https://masteringjs.io/tutorials/fundamentals/substring Chaînes de caractères en JavaScript], Maîtriser le JS.
</ref><ref>
[[gerrit:c/mediawiki/core/+/158108|Change 158108 - mediawiki/core]], {{ymd|2014|9|5}}, gerrit.wikimedia.org
</ref>

{{Anchor|Globals}}
<span id="Exporting"></span>
== Exportation ==
Utilisez directement les variables globales exposées par le navigateur (telles que document, location, navigator) et non comme des propriétés de l'objet window.
Cela améliore la confidentialité dans le code par l'analyse statique et peut également servir à d'autres fonctionnalités de l'IDE.
Outre les variables globales du navigateur, uniquement <code>mw</code>, <code>$</code> et <code>{{ll|OOUI|OO}}</code> sont sûres à utiliser.

Eviter de créer de nouvelles variables globales.
Évitez de modifier les variables globales ''qui n'appartiennent pas'' à votre code.
Par exemple, les variables globales embarquées telles que String ou Object ne doivent pas être étendues avec des méthodes d'utilité supplémentaires ; de même les fonctionnalités relatives à OOjs ou à jQuery ne doivent pas être assignées à ces variables globales.

Pour rendre une fonctionalité publique afin qu'elle soit réutilisée, utiliser <code>module.exports</code> à partir des {{ll|ResourceLoader/Package files|fichiers des paquets}}, et / ou assigner les propriétés présente dans la hiérarchie <code>mw</code>, comme <code>mw.echo.Foo</code>.

Noter que les variables de configuration exposées par MediaWiki doivent être accédées via <code>{{ll|Manual:Interface/JavaScript#mw.config|mw.config}}</code>.

<span id="Environment"></span>
=== Environnement ===
Modifier des prototypes intégrés tels que <code>Object.prototype</code> est considéré comme dangereux.
Cela n'est pas pris en charge dans le code de MediaWiki, et cassera probablement les fonctionnalités non liées.

<span id="Naming"></span>
== Nommage ==

Toutes les variables doivent être nommées en utilisant la notation ''[[w:fr:CamelCase|CamelCase]]'' avec la première lettre en minuscule, ou en utilisant que des majuscules (avec le caractère souligné '_' pour séparer les groupes de lettres) si la variable représente la valeur d'une certaine constante.

Toutes les fonctions doivent être nommées en utilisant la notation ''[[w:fr:CamelCase|CamelCase]]'', généralement avec la première lettre en minuscule sauf si la fonction est un constructeur de classe, auquel cas il faut commencer par une majuscule.
Il est préférable que les fonctions des méthodes commencent par un verbe comme par exemple <code>getFoo()</code> au lieu de <code>foo()</code>.

<span id="Acronyms"></span>
=== Abréviations ===
Les noms comportant des acronymes doivent traiter ces derniers comme un mot normal avec seulement la première lettre en majuscule si besoin.
Cela s'applique également aux abréviations sur deux lettres comme <code>Id</code>.
Par exemple <code>getHtmlApiSource</code> par opposition à ''getHTMLAPISource''.

=== jQuery ===
Différencier les nœuds du DOM des objets jQuery en préfixant les variables avec le signe dollar '$' quand elles représentent un objet jQuery, comme <code>$foo = $( '#bar' )</code>.
Ceci aide à réduire les erreurs où les tests utilisent des contrôles de condition incorrects, comme <code>if ( foo )</code> au lieu de <code>if ( $foo.length )</code>.
Là où les méthodes DOM retournent souvent nul (équivalent à ''faux''), les méthodes jQuery retournent un objet de collection mais vide (qui, comme les tableaux natifs et les autres objets JavaScript, sont ''vrai'').

=== npm ===

Lorsque vous publiez un projet indépendant sur npmjs.org, considérez que la publication se fait dans l'espace de noms <code>@wikimedia</code>.
Notez que certains projets indépendants prévus pour être utilisés hors de la communauté Wikimedia ont un nom unique qui leur suffit et un nom de paquet actuel sans espace de noms dédié (comme « oojs » et « visualeditor »).
[[phab:T239742|T239742]]

<span id="Creating_elements"></span>
== Création d'éléments ==

Pour créer un élément ordinaire, utilisez la syntaxe simple {{tag2|tag}} dans le constructeur jQuery :

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

Lorsque vous créez des éléments basés sur le nom de la balise à partir d'une variable (pouvant contenir du code html arbitraire) :

<syntaxhighlight lang="javascript">
// chercher 'span' ou 'div' etc.
tag = randomTagName();
$who = $( document.createElement( tag ) );
</syntaxhighlight>

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

== Collections ==
Les différents types de collections ont parfois l'air similaire et ont un comportement différent; ils doivent être traités comme tels.
Cette confusion vient principalement du fait que les tableaux JavaScript ressemblent aux tableaux des autres langages mais en réalité ils ne sont que des extensions de ''Object''.
Utilise les conventions suivantes :

{| class="wikitable plainlinks"
!  Action
!  Tableaux
!  Objets à plat
! [https://api.jquery.com/jQuery/  Objets jQuery]
|-
! Déclaration et initialisation vide
| {{jsi|1= x = [];}}
| {{jsi|1= x = {};}}
| {{jsi|1= $x = $( [] );}}
|-
!  Valeur accédée
| {{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>
|-
!  Taille
| {{jsi|x.length;}}
|<syntaxhighlight lang="javascript">
Object.keys( x ).length;
</syntaxhighlight>
| {{jsi|$x.length;}}
|-
!  Itération
| {{jsi|1= for ( i = 0; i < x.length; i++ ) {} }}<br />  or:<br /><code>x.forEach( function ( value, i ) {} );</code>
| {{jsi|for ( key in x ) {} }}
| <code>$x[https://api.jquery.com/each/ .each]( function ( i, element ) {} );</code>
|}

Évitez d'utiliser une boucle <code>for-in</code> pour itérer sur un tableau (contrairement à un objet à plat), car <code>for-in</code> entraînera de nombreux comportements inattendus, y compris : les clés en tant que chaînes, l'ordre d'itération instable, les indices pouvant sauter des valeurs, l'itération pouvant inclure d'autres propriétés non numériques.

<span id="Storage"></span>
== Stockage ==

Les clés de localStorage et / ou de sessionStorage doivent être accédées via <code>[[wmdoc:mediawiki-core/master/js/module-mediawiki.storage.html|mw.storage]]</code> ou <code>[[wmdoc:mediawiki-core/master/js/module-mediawiki.storage.html#.session|mw.storage.session]]</code>.

<span id="Keys"></span>
=== Clés ===
Les clés doivent commencer par <code>mw</code> et utiliser le format ''camelcase'' et / ou des tirets.
Ne pas utiliser le catactère souligné '_' ni d'autres séparateurs.
Exemples de clés réelles :

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

Notez bien qu'à la différence des cookies via mw.cookie, '''il n'existe pas''' de préfixe de wiki ou de préfixe de cookie ajouté par défaut.
Si les valeurs sont fonction du wiki, vous devez inclure manuellement <code>{{ll|Manual:Interface/JavaScript#mw.config|wgCookiePrefix}}</code> dans la clé.

<span id="Values"></span>
=== Valeurs ===

Les valeurs doivent être des chaînes. Attention, si vous essayez de stocker d'autres types de valeurs, celles-ci seront ''castées'' en chaîne (par exemple {{phpi|false}} deviendra {{phpi|"false"}}).

L'espace est limité.
Utiliser des valeurs courtes et concises sur les structures d'objets lorsque cela est possible.
Quelques exemples :

* Pour l'état booléen (true/false, étendu/réduit), utiliser <code>1</code>  ou <code>0</code>.
* Les valeurs toujours numériques doivent être stockées telles quelles et ''castées'' avec <code>Number</code> lors de leur utilisation (éviter <code>parseInt</code>).
* Pour les valeurs qui sont toujours des chaînes de caractères, conservez-les telles qu'elles sont.
* Pour les listes de valeurs définies par le logiciel, considérez les chaînes comme séparées par des virgules ',' ou par des barres verticales '|' afin de réduire l'espace et le coût de traitement.
* Pour les listes de valeurs pouvant être générées par l'utilisateur ou qui ont une nature complexe, utilisez JSON.

<span id="Eviction_strategy"></span>
=== Stratégie d'éviction ===
Rappelez-vous que le stockage local n'a pas de stratégie d'évacuation par défaut.
C'est pourquoi ceci doit être évité :

* Évitez d'utiliser des entrées générées par l'utilisateur pour construire des noms de clés.
* Évitez les clés qui contiennent des identifiants pour les entités générées par l'utilisateur (par exemple, les noms d'utilisateur, les noms de catégories, les identifiants de page ou les autres variables fournies par l'utilisateur ou par le système).
* D'une manière générale éviter les formes qui impliquent la création potentielle d'un grand nombre de clés de stockage.

Par exemple, si une fonctionnalité doit stocker l'état d'une entité variable (par exemple la page actuelle), il pourrait être logique d'utiliser une seule clé pour cette fonctionnalité globalement et limiter les informations stockées pour les dernières itérations (''Last Recent Used'').
La légère augmentation du coût de récupération (clé entière au lieu de clés plus petites séparées) est considérée acceptable car autrement le nombre de clés augmenterait de manière démesurée.

Même si les clés ne dépendent pas de l'entrée utilisateur, vous pouvez toujours utiliser une seule clé pour votre fonctionnalité car sinon les versions précédentes de votre logiciel auront stocké des données que vous ne pourrez pas nettoyer.
En utilisant une seule clé, vous pouvez revenir en arrière de manière à, naturellement, ne pas stocker les sous-propriétés inconnues.

L'utilisation d'une clé de suivi est également un anti-modèle et n'évite pas les problèmes ci-dessus, car cela ne fonctionnerait pas en raison des conditions de compétition sur le stockage web HTML5 partagé et non atomique entre plusieurs onglets ouverts du navigateur.

Lorsque l'utilisation du stockage local doit être supprimée pour la fonctionnalité, assurez-vous d'abord d'implémenter une stratégie d'évacuation pour nettoyer les anciennes valeurs.
On utilise généralement [[wmdoc:mediawiki-core/master/js/mw.html#.requestIdleCallback|mw.requestIdleCallback]] pour rechercher facilement la clé et la supprimer.
Voir [[phab:T121646|T121646]] pour une approche qui soit plus en rapport.

<span id="Personal_information"></span>
=== Informations personnelles ===
Évitez de stocker des informations personnelles en local car elles restent quand un utilisateur se déconnecte ou ferme son navigateur.
Utilisez plutôt le stockage de session.
Voir [[phab:T179752|T179752]].

<span id="Asynchronous_code"></span>
== Code asynchrone ==

Le code asynchrone doit suivre et être compatible avec la norme ''Promise''.

Si vous définissez une  méthode comme asynchrone pour être appelée à partir du code, vous pouvez construire en interne 
l'objet [[wikt:thenable|thenable]] renvoyé soit en utilisant [https://api.jquery.com/jquery.deferred/ $.Deferred] ou le  ''Promise'' natif.

Lorsque vous appelez une méthode asynchrone, utilisez uniquement les méthodes classiques compatibles avec ''Promise'' telles que <code>then()</code> et <code>catch()</code>.
Évitez d'utiliser les méthodes spécifiques de jQuery comme <code>done()</code> ou <code>fail()</code>, qui pourraient cesser de fonctionner sans prévenir si la méthode que vous appelez passe en interne de $.Deferred au ''Promise'' natif.

Notez qu'il reste également des comportements anciens et subtils dans les fonctions de rappel <code>done</code> et <code>fail</code>.
Faites très attention lorsque vous migrez du code existant de <code>done()</code> vers <code>then()</code> car il peut ne plus fonctionner correctement.
Plus précisément, les procédures de rappel <code>done</code> et <code>fail</code> invoquent les votres de manière synchrone si ''Deferred'' a été utilisé au moment où vous les avez attachées.
Cela signifie que la fonction de rappel peut être appelée avant que l'instruction d'attachement n'ait eu le temps de se terminer.

Par exemple :

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

console.log( "A" );
getSqrt( 49 ).done( function ( val ) {
    console.log( "C" ); // peut être A C B, ou, A B C
} );
console.log( "B" );

console.log( "A" );
getSqrt( 49 ).then( function ( val ) {
    console.log( "C" ); // toujours A B C
} );
console.log( "B" );

var y = getSqrt( 49 ).then( function ( val ) {
    console.log( y.state(), val ); // "résolu", 7
} );
var x = getSqrt( 49 ).done( function ( val ) {
    console.log( x.state(), val ); // Type d'erreur non récupéré : x n'est pas défini
} );
var z = getSqrt( 49 );
z.done( function ( val ) {
    console.log( x.state(), val ); // "résolu", 7
} );
</syntaxhighlight>

<span id="Final_notes"></span>
== Notes finales ==

<span id="Reuse_ResourceLoader_modules"></span>
=== Réutiliser les modules ResourceLoader ===
Ne réinventez pas la roue.
Beaucoup de fonctionnalités JavaScript et les utilitaires liés à MediaWiki sont fournis avec le noyau MediaWiki et sont stables et vous pouvez (littéralement) les utiliser dans vos dépendances.
Voir {{ll|ResourceLoader/Core modules}} avant de développer votre propre code.

<span id="Pitfalls"></span>
=== Pièges ===
* Veillez à préserver la compatibilité des langues LTR qui s'écrivent de gauche à droite et les RTL qui s'écrivent '''de droite à gauche''' (commme <code>float: right</code> ou <code>text-align: left</code>), particulièrement quand vous formatez des conteneurs de texte. En mettant ces déclarations dans le fichier CSS, elles seront automatiquement inversées pour les langues RTL par {{ll|CSSJanus}} en {{ll|ResourceLoader}}.
* Utiliser <code>[https://api.jquery.com/attr/ attr()]</code> et <code>[https://api.jquery.com/prop/ prop()]</code> selon le cas.<br /> Autres lectures :
** [https://api.jquery.com/attr/ jQuery#attr, jQuery API]
** [https://javascript.info/tutorial/attributes-and-custom-properties Attributs et propriétés personnalisées, javascript.info]
* En conséquence [https://api.jquery.com/category/selectors/attribute-selectors/ mettez des apostrophes] autour les valeurs du sélecteur d'attributs : <code>[foo="bar"]</code> au lieu de <code>[foo=bar]</code> ([https://bugs.jquery.com/ticket/8229 jqbug 8229]).
* À partir de jQuery 1.4 le constructeur jQuery a une nouvelle fonctionnalité qui permet de passer un objet dans le deuxième argument, comme : <syntaxhighlight lang=javascript inline>$( '<div>', { foo: 'bar', click: function () {}, css: { .. } } );</syntaxhighlight>. N'utilisez pas ceci. Ca rend le code plus difficile à suivre, échoue sur les attributs (tels que la taille 'size') qui sont aussi des méthodes, et c'est instable en raison de ce mélange de méthodes jQuery avec des attributs d'éléments. Une future méthode jQuery ou un greffon appelé « title » pourrait convertir un élément en titre, ce qui signifie que l'attribut titre ne peut plus être initialisé par cette méthode. Soyez explicite et appelez <code>.attr()</code>, <code>.prop()</code>, <code>.on()</code> etc. directement.

<span id="Use_CSS_for_styling_many_elements"></span>
=== Utiliser CSS pour styliser de nombreux éléments ===
N'appliquez pas de style à un grand nombre d'éléments à la fois car cela peut dégrader les performances.
Utilisez plutôt la classe d'un parent commun (ou ajoutez-en un) et appliquez le CSS dans un fichier <code>.css</code> ou <code>[[LESS|.less]]</code>.
Grâce à ResourceLoader, tout sera chargé dans la même requête HTTP, de sorte qu'il n'y a pas de dégradation des performances due à la présence d'un fichier CSS distinct.
Ne mettez pas de CSS dans les attributs "style" en ligne, n'insérez pas non plus d'éléments "style" à partir de JavaScript.

<span id="References"></span>
== Références ==
* [https://contribute.jquery.org/style-guide/js/ Guide de style pour JavaScript], contribution à jQuery
* [https://www.crockford.com/code.html Conventions de codage pour JavaScript], Douglas Crockford
* [https://www.youtube.com/watch?v=_EANG8ZZbRs Le style de la programmation et votre cerveau], Douglas Crockford sur YouTube

----
<references />

{{Conventions navigation}}

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