Manual:Coding conventions/fr

Cette page décrit les conventions de codage utilisées dans le code source de MediaWiki, incluant les conventions de nommage. Elle vise à décrire, non à dicter. Si vous choisissez de suivre les recommandations suivantes, il vous sera néanmoins plus facile de collaborer avec les autres participants au projet ; dans le cas contraire gardez en tête que vos contributions sont susceptibles d'être reformatées par d'autres.

Indentation et espacement

• Le code est indenté avec des tabulations, pas des espaces.
• Nous utilisons le style d'indentation K&R pour le positionnement des accolades. Elles sont ajoutées sur la même ligne que la déclaration de fonction, pas sur une nouvelle ligne.
• En général, une espace est utilisée dans les parenthèses non vides des déclarations et des appels de fonctions :

function wfExemple( $a, $b ) {
        // ...
}

Également : array( 1, 2, 3 ) plutôt que array(1,2,3)

Dans emacs (voir aussi php-mode ^(en)), vous pouvez reproduire approximativement ce style avec un « minor mode » personnalisé dans votre fichier .emacs :

(defconst mw-style 
      '((c-offsets-alist . (
                            (case-label . +)
                            (arglist-close . 0)
                            ))))
 
 
(c-add-style "MediaWiki" mw-style)
 
(define-minor-mode mw-mode
  "tweak style for mediawiki"
  nil " MW" nil
  (if mw-mode
      (progn
        (setq tab-width 4 c-basic-offset 4)
        (c-set-style "MediaWiki"))
    (kill-local-variable 'tab-width)
    (kill-local-variable 'c-basic-offset)))

Classes

• PHP 4 ne supportant pas les méthodes et les membres de classes « private », le code plus âgé sera annoté de ce mot en commentaire tel que /** @private */ pour souligner l'intention. Merci de respecter cette règle comme si elle était exécutée par le compilateur.

  Le code plus récent utilisera la visibilité appropriée, mais ne l'ajoutez pas au code existant sans une première vérification. Un test est nécessaire car la règle ci-dessus a été brisée à plusieurs endroits.

• En général, les variables membres sont nommées mXxx pour les distinguer, ce qui aide à détecter les oublis de $this qui causent une rupture due à l'initialisation silencieuse de la variable.
• Nous préfixons les noms des variables globales par wg (wiki global) dans le but de mieux les distinguer, ce qui aide à détecter des déclarations de variables globales erronées.

Conventions de nommage

La préférence va à la technique lowerCamelCase pour les noms des fonctions et des variables. Par exemple :

private function faitQuelqueChose( $userPrefs, $editSummary ) {

D'autres préfixes sont utilisés :

Fonctions

• wf (wiki functions) - Fonctions de haut niveau, par exemple function wfFuncname() { ... }

Variables

• wg - Variables globales, par exemple $wgVersion, $wgTitle
• m - Variables membres d'objets : $this->mPage

  Ce n'est pas universellement respecté, mais tentez de rester constant dans une même classe.

Fonctions et variables d'extensions

• ef (extension functions) - Fonctions de haut niveau
• eg - (extension globals) - Variables

Variables HTTP et de session

• ws - Variables de session : $_SESSION['wsSessionName']
• wc - Variables de cookie : $_COOKIE['wcCookieName']
• wp - Variables POST (via les champs de formulaire) : ^(en) $wgRequest->getText('wpLoginName')

Base de données

• Les noms des relations (tables) sont habituellement des noms communs au singulier : user, page, revision, etc.
  • Exceptions : pagelinks, categorylinks...
• Les noms des champs (colonnes) ont un préfixe dérivé du nom de la relation (le nom lui-même s'il est court, une abréviation dans le cas contraire) :
  • page -> page_id, page_namespace, page_title...
  • categorylinks -> cl_from, cl_namespace...

Variables locales courantes

Il est fréquent de travailler avec des instances de la classe Database ; nous avons une convention de nommage pour celles-ci qui permet de garder la trace de la nature du serveur sur lequel nous sommes connectés. Cela revêt une importance particulière pour les environnements usant de réplication, comme les grands wikis.

• $dbw - Un objet de Database pour l'écriture (connexion au maître)
• $dbr - Un objet de Database pour la lecture (peut être une connexion à l'esclave en lecture seule, légèrement en-deçà de l'état "maître")

Documentation du code

• Le style de documentation Doxygen est utilisé (l'usage que nous en faisons est similaire à PHPDoc ^(en)). Par exemple, donner une description d'une fonction ou d'une méthode, ce qu'elles renvoient (@return), leurs paramètres (@param), ou bien @package, @subpackage, @author... Merci d'utiliser l'arobase plutôt que l'antislash, car bien que les deux fonctionnent avec Doxygen, seule l'arobase fonctionne avec PHPDoc.
• Le format standard des paramètres est le suivant : @param $varname [type] [description]. Assurez-vous de mettre $varname avant [type].

Messages

• Quand vous créez un nouveau message, utilisez le trait d'union autant que possible ^(en). Par exemple, "some-new-message" est un bon nom, alors que "someNewMessage" et "some_new_message" n'en sont pas.
• Si le message doit se terminer par un deux-points, ne mettez pas le deux-points dans le code, mais plutôt dans le texte du message. La manière de traiter le deux-points varie selon certaines langues (en français, il se doit d'être précédé d'une espace).
• Les attributs HTML class et ID devraient être préfixés par mw-. Il est pratique courante de séparer chaque mot par un trait d'union (mw-some-new-class) plutôt que mw-somenewclass ou mw-some_new_class, mais à l'heure actuelle aucune convention ne régit cet usage.