Utilisateur:Carfois/Conseils pour la programmation des modèles
Bonnes pratiques
Cette page a pour objectif de fournir un ensemble de conseils en matière de programmation de modèles.
Remarques :
- ces conseils sont partie issus de ce qui se fait sur Wikipédia, et pour partie issus des bonnes pratiques générales en matière de programmation ;
- cette page n'aborde pas le comment programmer ces modèles : voir les pages d'aide et Utilisateur:Juju2004/Astuces_pour_la_programmation_des_modèles.
Mise en forme du code
[modifier | modifier le code]La mise en forme du code est rendue difficile car chaque retour à la ligne introduit un espace dans le code. Néanmoins, il est possible d'utilier le fait que les ParserFunctions exécutent un trim sur leurs arguments pour mettre en forme le code ainsi :
{{#if:<test>
| then
| else
}}
Evidemment, un simple #if peut conserver la forme en ligne :
{{#if:<test>|then}}
Gestion des erreurs
[modifier | modifier le code]L'utilisation par chaque modèle d'une stratégie différente de gestion des erreurs entraîne des difficultés de maintenance. Il existe des modèles décrits Modèle:Fonctions modèle qui permettent de traiter les erreurs de manière unifiée.
Paramètre non renseigné
[modifier | modifier le code]La forme :
{{{param1|<font color="red">veuillez renseigner le paramètre 1</font>}}}
n'apporte strictement rien à la forme :
{{{param1}}}
qui affiche {{{param1}}} si le paramètre n'est pas renseigné. Elle est à exclure.
De même, le modèle {{Fonctions modèle/paramètre manquant}} est à utiliser avec retenue.
Factorisation : les fonctions
[modifier | modifier le code]Il est préférable de n'écrire un code qu'une seule fois, ce qui limite le risque d'erreur et la facilite la maintenance du modèle. En programmation structurée, on utilise des fonctions. En syntaxe wiki, la manière de créer des fonctions est de créer un sous-modèle qui sera appelé plusieurs fois par le modèle principal.
On nommera fonction un sous-modèle qui n'est jamais utilisé directement dans la rédaction des articles, mais toujours appelé par un modèle. Voici quelques règles concernant les fonctions :
- Les fonctions devraient toujours être des modèles placés dans une sous-page de l'espace modèle ;
- Ces sous-pages devraient toujours commencer par une minuscule ;
- Les fonctions devraient avoir une 'syntaxe normalisée, c'est-à-dire où tous les paramètres sont nommés de manière explicite.
- Les fonctions devraient être rassemblées, dans la mesure du possible, par domaine plutôt que par modèle d'appel, ce qui évitera de réécrire plusieurs fois des fonctions très similaires appelées par des modèles différents. Il est donc utile de développer des des modèles "Modèle:Fonctions <domaine>/<fonction>". ;
- Les fonctions devraient posséder une sous-page de tests, sous la forme ""Modèle:Fonctions <domaine>/<fonction>/tests".
Remarque : lorsqu'une fonction est aussi un modèle, il est possible de créer un modèle interface dont la syntaxe sera moins lourde, avec des paramètres implicites.
Paramètres
[modifier | modifier le code]Nommage des paramètres
[modifier | modifier le code]Il est préférable de nommer les paramètres d'un modèle. Cependant, pour des questions de simplicité d'utilisation, il existe des exceptions :
| Nombre de paramètres | Nommé ou non |
|---|---|
| 1 | jamais |
| 2 | au choix |
| plus | au choix pour les deux premiers ; les paramètres à partir du troisième sont toujours nommés |
Remarque : les paramètres d'une fonction devraient toujours être nommés. La syntaxe est moins ambiguë, bien que plus lourde, mais cette lourdeur n'est pas gênante pour le contributeur car la fonction n'est jamais utilisée directement dans le Main.
Le contenu des paramètres
[modifier | modifier le code]Il est préférable de laisser le modèle réaliser le plus de travail possible, en partant des paramètres sous leur forme brute. En particulier, on laissera le modèle gérer les wikiliens. Par exemple, on préfèrera écrire :
{{<modèle>|nom=Géorgie|lien=Géorgie (pays)}}
à :
{{<modèle>|nom=[[Géorgie (pays)|Géorgie]]}}
En effet, on peut souhaiter étendre l'usage d'un modèles, mais cela suppose le plus souvent que les paramètres ne soient pas enrichis d'une mise en forme. Les changements éventuels de syntaxe sont également facilités par cette décomposition.
Les paramètres alternatifs
[modifier | modifier le code]La forme
{{{param1|{{{param2|{{{param3|{{{param4|}}}}}}}}}}}}
qui permet d'éviter des #if est à éviter en raison de l'accumulation d'accolades fermantes en fin de code.
Exception : pour passer des paramètres à une fonction, ont peut accepter la forme :
{{fonction|x= {{{param1|{{{param2|}}}}}} }}
Les syntaxes alternatives
[modifier | modifier le code]Modèle complexe
[modifier | modifier le code]Lorsqu'un modèle est complexe et possède plusieurs syntaxes alternatives, il est plus simple de développer une sous-page "Modèle:<nom du modèle>/syntaxe normalisée" ou tous les paramètres sont nommés. L'appel du modèle "interface" devient un aiguilleur qui analyse les paramètres et les renvoie vers la syntaxe normalisée.
Modification d'un modèle
[modifier | modifier le code]Lorsqu'un modèle subit une modification importante, avec changement de syntaxe et de comportement, la solution suivante est utile :
- Renommer le modèle actuel en "Modèle:<nom du modèle>/ancienne syntaxe.
- Nommer le nouveau modèle "Modèle:<nom du modèle>/nouvelle syntaxe"
- Créer un aiguilleur de syntaxe qui catégorise une page utilisant le modèle déprécié dans une catégorie adaptée.
Exemple pour <nom du modèle> :
{{#if:<test>
|{{<nom du modèle>/nouvelle syntaxe|<transmission de paramètres>}}
|{{Fonctions modèle/syntaxe dépréciée|modèle=<nom du modèle>}}{{<nom du modèle>/ancienne syntaxe|<transmission de paramètres>}}
}}