Convention:Modules
Conventions pour les modules
Cette page vous présente la nature des modules et les conventions de codage. Voir aussi la page d’aide associée.
Les modules sont des pages au sein du Wiktionnaire qui contiennent des scripts en Lua servant au fonctionnement de certains modèles.
Conventions de nommage
Le code doit être écrit en anglais afin de faciliter la réutilisation par d’autres wikis non francophones.
Les modules utilisent l’espace de noms appelé Module:. Leur nom peut être similaire à une page de l’espace de nom Modèle: qui fait appel à lui. S’il contient des données, le nom du module se termine par /data.
Nommage des variables
Variables locales
Les variables doivent être nommées selon la notation lowerCamelCase :
- pas de majuscule au début,
- majuscule à chaque début de mot.
Par exemple, une variable qui contiendrait le nom d’une langue serait nommée languageName.
La variable d’export (celle qui est retournée à la fin du module) doit être nommée p.
Variables de modules
Les variables contenant des modules importés suivent les mêmes règles que ci-dessus mais avec l’ajout d’un préfixe m_ suivi du nom du module. Par exemple, la variable qui contiendrait le module bases serait nommée m_bases. Ce qui donnerait local m_bases = require("Module:bases").
Constantes
Les constantes doivent être nommées selon la notation suivante :
- tout en majuscules,
- un tiret bas ‹ _ › entre chaque mot.
Nommage des fonctions
Les conventions de codage recommandent les points suivants :
- lowerCamelCase,
- ajouter un tiret bas au début du nom des fonctions qui ne prennent pas d’objet
frame.
L’unique paramètre des fonctions qui sont invoquées depuis les modèles doit être appelé frame.
Indentation, retours à la ligne et espaces
L’indentation avec 2 ou 4 espaces est fortement recommandée.
Structure des scripts
Il est recommandé de ne mettre qu’une instruction par ligne, même lorsque cette instruction est courte.
Chaque déclaration de fonction doit être séparée par une ligne vide.
Commentaires et documentation
Les commentaires et la documentation incluse doivent être écrits en anglais afin de faciliter la réutilisation par d’autres wikis non francophones. La documentation du module (celle rédigée dans la sous-page /Documentation) doit être rédigée en français afin que tous les contributeurs francophones puissent la lire sans soucis.
La documentation des fonctions doit utiliser trois tirets (---) au lieu de deux seulement pour les commentaires simples.
Les paramètres doivent suivre un formatage précis :
--- @param <nom param> <type> <commentaire>
Dans le cas du paramètre frame, le format est différent :
--- Parameters:
--- frame.args (<type>): <commentaire>
Si un paramètre possède des alias, on les met sur la même ligne, séparés par des barres obliques ‹ / ›.
--- Parameters:
--- frame.args/frame.args (<type>): <commentaire>
Dans le cas ou la fonction utilise l’objet frame du parent, --- frame.args sera remplacé par --- parent frame.args.
La valeur de retour doit suivre le format suivant :
--- @return <type> <commentaire>
Catégorisation
Pour catégoriser un module, il faut passer par sa /Documentation. Par exemple :
<includeonly> ] </includeonly>