Manual:Coding conventions/fr

Cette page décrit les conventions de codage utilisées dans le code de base de MediaWiki et les extensions utilisées pour les sites web Wikimedia, y compris les conventions de nommage correspondantes. Les modifications qui ne suivent pas ces conventions peuvent être sommairement -1'ed par les relecteurs de code; ceci doit être considéré comme une invitation à corriger les problèmes de style et mettre à jour le patch.

Cette page liste les conventions générales qui s'appliquent à l'ensemble du code MediaWiki, quelquesoit le langage dans lequel il est écrit. Pour les instructions concernant des composants spécifiques ou des types de fichiers particuliers de MediaWiki, voir:


 * SVG
 * SVG

Sur Wikitech (s'applique au moins aux opérations/puppet):


 * Puppet

Largeur des tabulations
Les lignes doivent être indentées avec un seul caractère Tab par niveau d'indentation. Ne faites pas de supposition sur le nombre d'espaces par Tab. La plupart des développeurs MediaWiki estiment que 4 espaces par Tab conviennent bien pour la lisibilité, mais beaucoup de systèmes sont configurés pour utiliser 8 espaces par Tab et certains développeurs peuvent utiliser aussi 2 espaces par Tab.

Pour les utilisateurs vim, une manière de faire ces initialisations est d'ajouter ce qui suit à $HOME/.vimrc:

autocmd Filetype php setlocal ts=4 sw=4

avec des lignes semblables pour CSS, HTML et JavaScript.

Néanmoins, pour Python, suivez à la place le guide concernant les espaces de PEP 8, qui recommande les espaces pour les nouveaux projets.

Nouvelles lignes
Tous les fichiers doivent utiliser le passage à la ligne du style Unix (caractère LF uniquement, et non une combinaison CR+LF).


 * git sous Windows va (par défaut) convertir les passages à la ligne CR+LF en LF lors de la validation (commit).

Tous les fichiers doivent se terminer par un retour à la ligne.


 * Cela a un sens parce que toutes les autres lignes ont un caractère de nouvelle ligne à la fin.
 * Cela aide à faire circuler plus facilement les données en formats non binaires (comme les diffs).
 * Les outils en ligne de commande comme cat et wc ne manipulent pas les fichiers si aucun n'est bon (ou au moins, pas de la manière que l'on voudrait ou que l'on souhaiterait).

Encodage
Tous les fichiers texte doivent être encodés avec UTF-8 sans Byte Order Mark (BOM).

N'utilisez pas Microsoft Notepad pour modifier vos fichiers, parce qu'il insère toujours un BOM. Le BOM arrête l'exécution des fichiers PHP parce que c'est un caractère spécial tout au début du fichier et qu'il est produit par le navigateur web au client.

Bref, assurez-vous que votre éditeur prend en charge UTF-8 sans BOM.

Caractères espaces de fin de ligne
Quand vous utilisez un IDE, en pressant les touches Home et End (parmi d'autres raccourcis clavier) vous ignorez habituellement les espaces de fin et à la place vous sautez à la fin du code, ce qui est le but. Pour les éditeurs de texte non-IDE, au contraire, en pressant End vous allez à l'extémité complète de la ligne, ce qui signifie que le développeur doit revenir en arrière à travers les espaces de fin pour revenir finalement à l'endroit où il voulait entrer son texte.

Enlever les espaces de fin est une opération triviale pour la plupart des éditeurs de texte. Les développeurs doivent éviter d'ajouter des espaces après la fin, principalement sur les lignes qui contiennent d'autre code visible.

Certains outils rendent cela plus facile:


 * nano: GNU nano 3.2;
 * : dans Enregistrer les options du menu "Editer > Préférences", active "Supprimer les espaces et les marqueurs de fin de ligne" et "Nettoyer seulement les lignes modifiées";
 * Kate: vous pouvez voir les espaces de fin en activant l'option "Metre en valeur les espaces de fin". Cette option se trouve dans "Paramètres > Configurer Kate > Aspect". Vous pouvez aussi dire à Kate de nettoyer les espaces de fin lors de l'enregistrement dans "Paramètres > Configurer Kate > Ouvrir/Enregistrer".
 * vim: divers plugin de nettoyage automatique;
 * Sublimer le texte: plugin TrailingSpaces.

Mots-clé
N'utilisez pas de parenthèses avec des mots-clé (comme,  ) là où ce n'est pas nécessaire.

Style général
Le style d'indentation de MediaWiki est similaire à ce que l'on appelle le "style à une parenthèse vraie" (One True Brace Style). Les parenthèses sont ainsi placées sur la même ligne que le début de la fonction, de la condition, de la boucle, etc. Le else/elseif est placé sur la même ligne que la parenthèse fermante qui le précède.

Les instructions qui s'écrivent sur plusieurs lignes ont leur seconde ligne et les suivantes indentées d'un niveau supplémentaire:

Utilisez l'indentation et le passage à la ligne suivante pour clarifier la structure logique de votre code. Les expressions qui imbriquent des niveaux multiples de parenthèses ou des structures similaires peuvent commencer un nouveau niveau d'indentation avec chaque niveau d'imbrication:

Dans les instructions « switch » indentez à l'intérieur des parenthèses et entre les instructions « case »:

Alignement vertical
Evitez l'alignement vertical. Il a tendance à créer des diffs difficiles à interpréter, parce que la largeur autorisée pour la colonne de gauche doit sans cesse augmenter au fur et à mesure que des éléments sont ajoutés.

Quand c'est nécessaire, créez un alignement vertical sur la ligne du milieu avec des espaces plutôt que des tabulations. Par exemple, ceci :

Se réalise ainsi avec les espaces remplacés par des points:

 $namespaceNames·=·[ → NS_MEDIA············=>·'Media', → NS_SPECIAL··········=>·'Special', → NS_MAIN·············=>·'', ]; (Si vous utilisez le plugin vim de tabulation, en entrant :Tabularize /= vous alignerez les signes '='.)

Continuation de ligne
Les lignes doivent s'arrêter entre les colonnes 80 et 100. Il existe quelques rares exceptions à cela. Les fonctions qui prennent beaucoup de paramètres ne font pas exception.

L'opérateur qui sépare deux lignes doit être placé à la fin de la ligne précédente.

When continuing "if" statements, a switch to Allman-style braces makes the separation between the condition and the body clear:

Opinions differ on the amount of indentation that should be used for the conditional part. Using an amount of indentation different to that used by the body makes it more clear that the conditional part is not the body, but this is not universally observed.

Continuation of conditionals and very long expressions tend to be ugly whichever way you do them. So it's sometimes best to break them up by means of temporary variables.

Structures de contrôle sans parenthèses
Do not write "blocks" as a single-line. They reduce the readability of the code by moving important statements away from the left margin, where the reader is looking for them. Remember that making code shorter doesn't make it simpler. The goal of coding style is to communicate effectively with humans, not to fit computer-readable text into a small space.

This avoids a common logic error, which is especially prevalent when the developer is using a text editor which does not have a "smart indenting" feature. The error occurs when a single-line block is later extended to two lines:

Modifié ultérieurement en:

Ceci a la capacité de créer des bogues subtiles.

Style emacs
Dans emacs, en utilisant  de nXHTML mode, vous pouvez définir un mode mineur MediaWiki dans votre fichier .emacs:

The above  function will check your path when   is invoked to see if it contains “mw” or “mediawiki” and set the buffer to use the   minor mode for editing MediaWiki source. You will know that the buffer is using  because you'll see something like “PHP MW” or “PHP/lw MW” in the mode line.

Construction des URL
Never build URLs manually with string concatenation or similar. Always use the full URL format for requests made by your code (especially POST and background requests).

You can use the appropriate or  method in PHP, the  magic word in wikitext, the mw.util.getURL method in JavaScript, and similar methods in other languages. You'll avoid issues with unexpected short URL configuration and more.

Nommage des fichiers
Files which contain server-side code should be named in UpperCamelCase. This is also our naming convention for extensions. Name the file after the most important class it contains; most files will contain only one class, or a base class and a number of descendants. For example,  contains only the   class;   contains the   class, and also its descendants   and.

Fichiers des points d'accès
Name "access point" files, such as SQL, and PHP entry points such as  and , in lowercase. Maintenance scripts are generally in lowerCamelCase, although this varies somewhat. Files intended for the site administrator, such as readmes, licenses and changelogs, are usually in UPPERCASE.

N'utilisez jamais les espaces dans les noms de fichiers ou de répertoires, et n'utilisez jamais les caractères non-ASCII. Pour les titres en minuscules, les tirets sont préférables aux caractères soulignés.

Fichiers JS, CSS, et de média
For JavaScript, CSS and media files (usually loaded via ResourceLoader) file naming should match module naming. For example:
 * Module  might have files   and
 * module  has file

Modules names registered by extensions should follow name like, for instance:

This keeps it easy to find files, even if you divide up a module into smaller files for editing convenience and then bundle them together into a single module.

Documentation
The language-specific subpages have more information on the exact syntax for code comments in files, e.g. comments in PHP for doxygen. En utilisant la syntaxe précise, vous pourrez générer la documentation à partir du code source, sur http://doc.wikimedia.org.

Some elements of MediaWiki are documented in core's. For instance, if you add a new hook, you should update with the name of the hook, a description of what the hook does, and the parameters used by the hook.

Fichiers texte
Les développeurs peuvent garder les fichiers de documentation dans Git à côté du code. This can be good for detailed documentation of extension architecture, database design, etc. that you should update with each code commit that changes behavior. Les pages de mediawiki.org relatives à la documentation dans Git doivent déclarer le lien en utilisant.

(La possibilité de transclure du texte à partir des fichiers Git vers l'intérieur des pages wiki est répertoriée dans T91626.)

Notez que beaucoup de pages de documentation technique sur les pages mediawiki.org documentent l'évolution du code MediaWiki sur plusieurs versions. Décrivez les modifications dans votre document ou mettez le à jour en décrivant simplement la dernière base de code du "master".

Formats des fichiers texte

 * Si votre texte est du texte wiki, donnez lui une extension  . GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer). Par exemple, le   de l'extension Wikibase dans GitHub.
 * Si votre texte est du texte wiki, donnez lui une extension  . GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer). Par exemple, le   de l'extension Wikibase dans GitHub.


 * Doxygen supports Markdown formatting, so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's , in  and on GitHub).
 * Doxygen supports Markdown formatting, so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's , in  and on GitHub).


 * no extension and
 * Doxygen by default parses these as C language files (!!, tracked in ). You can take advantage of this by making the file mimic a C comment, and then add doxygen directives to the file. For example, generates File backend design in doxygen, and begins with:




 * Special:Version/Credits assumes  and   (with no extension) are wikitext files.

Entêtes des fichiers source
Pour être conforme avec la plupart des licenses vous devez avoir quelque chose de similaire à ceci (spécifique aux applications PHP GPLv2) au début de chaque fichier source.

Licences
Les licenses sont généralement référencées par leur nom complet ou un acronyme comme pour le SPDX standard. Voir aussi Manual:$wgExtensionCredits#license.

Notes des versions
You must document all significant changes (including all fixed bug reports) to the core software which might affect wiki users, server administrators, or extension authors in the  file. is in development; on every release we move the past release notes into the  file and start afresh. is generally divided into three sections:


 * Configuration changes is the place to put changes to accepted default behavior, backwards-incompatible changes, or other things which need a server administrator to look at and decide "is this change right for my wiki?". Try to include a brief explanation of how the previous functionality can be recovered if desired.
 * Bug fixes is the place to note changes which fix behavior which is accepted to be problematic or undesirable. These will often be issues reported in Phabricator, but needn't necessarily.
 * New features is, unsurprisingly, to note the addition of new functionality.

There may be additional sections for specific components (e.g. the Action API) or for miscellaneous changes that don't fall into one of the above categories.

In all cases, if your change is in response to one or more issues reported in Phabricator, include the task ID(s) at the start of the entry. Add new entries in chronological order at the end of the section.

Messages système
When creating a new system message, use hyphens (-) where possible instead of CamelCase or snake_case. So for example,  is a good name, while   and   are not.

If the message is going to be used as a label which can have a colon after it, don't hardcode the colon; instead, put the colon inside the message text. Some languages (such as French which require a space before) need to handle colons in a different way, which is impossible if the colon is hardcoded. The same holds for several other types of interpunctuation.

Try to use message keys "whole" in code, rather than building them on the fly; as this makes it easier to search for them in the codebase. For instance, the following shows how a search for  will not find this use of the message key if they are not used as a whole.

If you feel that you have to build messages on the fly, put a comment with all possible whole messages nearby:

Voir la Localisation pour davantage de conventions concernant la créatiion, l'usage, la documentation et la maintenance des clés de messages.

Orthographe préférée
It is just as important to have consistent spelling in the UI and codebase as it is to have consistent UI. By long standing history, 'American English' is the preferred spelling for English language messages, comments, and documentation.

Abbréviations des clés de messages

 * ph
 * emplacement à substituer (texte des champs d'entrée)


 * tip
 * texte de la bulle d'aide


 * tog-xx
 * gérer les options dans les préférences utilisateur

Ponctuation
Les messages d'erreur qui ne sont pas des titres sont considérés comme des phrases et doivent avoir une ponctuation.

Chargeur de ressources
Module names should match the main definition of the scripts they load. For example a module defining the  object is named "mediawiki.util" and the module for the   object constructor is named "mediawiki.Title".

Modules du coeur
If you need some additional functionality of a core module (or you need a function that does something similar but a different), actually improve the core module. Don't just copy+paste and modify the code in another place.

Remise en forme du code
Restructurez le code aussitôt que les modifications sont faites: n'attendez pas que le code s'enlaidisse au fur et à mesure des modifications.

Néanmoins, utilisez des commits séparés si votre restructuration est importante. Voir aussi les Instructions pour l'architecture (ébauche).

HTML
MediaWiki HTTP responses output HTML that can be generated by one of two sources. The MediaWiki PHP code is a trusted source for the user interface, it can output any arbitrary HTML. The Parser converts user-generated wikitext into HTML, this is an untrusted source. Complex HTML created by users via wikitext is often found in the "Template" namespace. HTML produced by the Parser is subject to sanitization before output.

Most data attributes are allowed to be used by users in wikitext and templates. But, the following prefixes have been restricted and are not allowed in wikitext. This enables client JavaScript code to determine whether a DOM element came from a trusted source:


 * – Cet attribut est présent dans le HTML généré par les widgets OOUI.
 * – attribut réservé à usage interne pour Parsoid.
 * et  – sont des attributs réservés à usage interne du coeur de MediaWiki, des habillages et des extensions. Le   est aussi utilisé par Parsoid.

En sélectionnant des éléments dans JavaScript, on peut préciser un attribut clé/valeur pour s'assurer que seulement les éléments DOM de la source présumée de confiance, sont pris en compte. Exemple: Ne gèrer que l'accroche 'wikipage.diff' pour les diffs officiels.

Liens externes

 * outils de style pour le code