<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
+
<body bgcolor="#ffffff">
+
<h1>Directives pour la programmation</h1>
-<p class="normaltext">Tout projet où l'on travaille en collaboration
-nécessite une cohérence et une stabilité fortes.</p>
-<p class="normaltext">L'objectif de ces directives est de
-fournir un cadre à respecter pour tout le code de Moodle. Il
-est vrai que certaines parties plus anciennes du code ne
-les respectent pas toujours ; le code sera corrigé. Tout le
-nouveau code doit absolument respecter ces directives
-aussi précisément que possible.</p>
+
+<p class="normaltext">Tout projet où l'on travaille en collaboration nécessite une cohérence et une stabilité fortes.</p>
+
+<p class="normaltext">L'objectif de ces directives est de fournir un cadre à respecter pour tout le code de Moodle. Il est vrai que certaines parties plus anciennes du code ne les respectent pas toujours ; le code sera corrigé. Tout le nouveau code doit absolument respecter ces directives aussi précisément que possible.</p>
+
<h2>Règles générales</h2>
+
<ol class="normaltext">
- <li class="spaced">Tous les fichiers contenant du code doivent
- avoir l'extension .php.</li>
- <li class="spaced">Tous les fichiers modèles doivent avoir
- l'extension .html.</li>
- <li class="spaced">Tous les fichiers textes doivent être ne
- format texte Unix (la plupart des éditeurs de texte
- permettent cela).</li>
- <li class="spaced">Toutes les balises php doivent être
- en forme complète, par exemple <font color="#339900"><?php
- ... ?></font> et non en forme abrégée comme
- <font color="#339900"><?php ... ?></font>.</li>
- <li class="spaced">Toutes les indications de copyright doivent
- être conservée. Vous pouvez ajouter les vôtres au besoin.</li>
- <li class="spaced">Tous les fichiers doivent inclure le
- fichier config.php principal.</li>
- <li class="spaced">Tous les fichiers doivent vérifier que
- l'utilisateur est correctement authentifié, à l'aide de require_login()
- et d'une des fonctions isadmin(), isteacher(), iscreator() ou isstudent().</li>
- <li class="spaced">Tous les accès aux bases de données doivent
- autant que possible utiliser les fonctions définies dans
- lib/datalib.php. Ceci permet la compatibilité avec un grand
- nombre de marques de bases de données. Il est possible de
- faire presque tout avec ces fonctions. Si vous devez écrire du code SQL,
- assurez-vous qu'il soit : multi-plateforme, restreint à des fonctions
- spécifiques de votre code (habituellement placés dans un fichier lib.php)
- et clairement marqué.</li>
- <li class="spaced">Ne créez et n'utilisez aucune variable locale,
- sauf les variables standard $CFG, $SESSION, $THEME et $USER.</li>
- <li class="spaced">Toutes les variables doivent être initialisées
- ou au moins leur existence doit être testée avec isset() ou
- empty() avant leur utilisation.</li>
- <li class="spaced">Toutes les chaînes de caractères doivent
- être traduisibles. Créez les nouvelles chaînes dans les fichiers
- du dossier « lang/en », donnez-leur des noms en minuscules,
- brefs, en anglais, et utilisez-les dans votre code par l'intermédiaire
- des fonctions get_string() ou print_string().</li>
- <li class="spaced">Tous les fichiers d'aide doivent être
- traductibles. Créez-les dans le dossier « lang/en/help » et
- appelez-les avec la fonction helpbutton().</li>
+
+<li class="spaced">Tous les fichiers contenant du code doivent avoir l'extension .php.</li>
+
+<li class="spaced">Tous les fichiers modèles doivent avoir l'extension .html.</li>
+
+<li class="spaced">Tous les fichiers textes doivent être ne format texte Unix (la plupart des éditeurs de texte permettent cela).</li>
+
+<li class="spaced">Toutes les balises php doivent être en forme complète, par exemple <font color="#339900"><?php ... ?></font> et non en forme abrégée comme <font color="#339900"><?php ... ?></font>.</li>
+
+<li class="spaced">Toutes les indications de copyright doivent être conservée. Vous pouvez ajouter les vôtres au besoin.</li>
+
+<li class="spaced">Tous les fichiers doivent inclure le fichier config.php principal.</li>
+
+<li class="spaced">Tous les fichiers doivent vérifier que l'utilisateur est correctement authentifié, à l'aide de require_login() et d'une des fonctions isadmin(), isteacher(), iscreator() ou isstudent().</li>
+
+<li class="spaced">Tous les accès aux bases de données doivent autant que possible utiliser les fonctions définies dans lib/datalib.php. Ceci permet la compatibilité avec un grand nombre de marques de bases de données. Il est possible de faire presque tout avec ces fonctions. Si vous devez écrire du code SQL, assurez-vous qu'il soit : multi-plateforme, restreint à des fonctions spécifiques de votre code (habituellement placés dans un fichier lib.php) et clairement marqué.</li>
+
+<li class="spaced">Ne créez et n'utilisez aucune variable locale, sauf les variables standard $CFG, $SESSION, $THEME et $USER.</li>
+
+<li class="spaced">Toutes les variables doivent être initialisées ou au moins leur existence doit être testée avec isset() ou empty() avant leur utilisation.</li>
+
+<li class="spaced">Toutes les chaînes de caractères doivent être traduisibles. Créez les nouvelles chaînes dans les fichiers du dossier « lang/en », donnez-leur des noms en minuscules, brefs, en anglais, et utilisez-les dans votre code par l'intermédiaire des fonctions get_string() ou print_string().</li>
+
+<li class="spaced">Tous les fichiers d'aide doivent être traductibles. Créez-les dans le dossier « lang/en/help » et appelez-les avec la fonction helpbutton().</li>
+
+<li class="spaced">Les magic_quotes sont automatiquement appliquées aux données en provenance du navigateur (envoyées via GET or POST), indépendamment des réglages de PHP. Il est donc sûr de les insérer directement dans la base de données. Toutes les autres données brutes (en provenance de fichiers ou de bases de données) doivent être encodées avec <font color="#339900">addslashes()</font> avant de les insérer dans la base de données.</li>
+
+<li class="spaced">IMPORTANT : tous les textes dans Moodle, tout particulièrement ceux qui proviennent des utilisateurs, doivent être affichés à l'aide de la fonction format_text(). Ceci permet de s'assurer que le texte est filtré et nettoyé correctement.</li>
+
</ol>
+
<p> </p>
+
<h2>Style du code</h2>
-<p class="normaltext">Je suis conscient qu'il est ennuyeux de changer
-votre style si vous avez d'autres habitudes, mais comparez cet embêtement
-avec les gros ennuis qu'ont ultérieurement les personnes qui
-essaient de comprendre un code composé avec des styles différents. Bien
-sûr il y a des avantages et des inconvénients à n'importe quel style,
-mais le style de Moodle <strong>existe</strong>, alors tenez-vous y,
-s'il vous plaît.</p>
+
+<p class="normaltext">Je suis conscient qu'il est ennuyeux de changer votre style si vous avez d'autres habitudes, mais comparez cet embêtement avec les gros ennuis qu'ont ultérieurement les personnes qui essaient de comprendre un code composé avec des styles différents. Bien sûr il y a des avantages et des inconvénients à n'importe quel style, mais le style de Moodle <strong>existe</strong>, alors tenez-vous y, s'il vous plaît.</p>
+
<ol class="normaltext">
- <li class="spaced">L'<strong>indentation</strong> doit être
- de 4 espaces. N'utiliser pas <strong>DU TOUT</strong> de tabulations.</li>
- <li class="spaced">Les <strong>noms des variables</strong> doivent toujours
- être des mots anglais faciles à lire, ayant une signification claire et
- en minuscules. Si vous avez vraiment besoin de plusieurs mots,
- concaténez-les, mais gardez-les aussi courts que possible.
- Utilisez des noms au pluriel pour les tableaux d'objets.
+
+<li class="spaced">L'<strong>indentation</strong> doit être de 4 espaces. N'utiliser pas <strong>DU TOUT</strong> de tabulations.</li>
+
+<li class="spaced">Les <strong>noms des variables</strong> doivent toujours être des mots anglais faciles à lire, ayant une signification claire et en minuscules. Si vous avez vraiment besoin de plusieurs mots, concaténez-les, mais gardez-les aussi courts que possible. Utilisez des noms au pluriel pour les tableaux d'objets.
<p class="examplecode"><font color="#006600">BON : $quiz<br />
BON : $errorstring<br />
BON : $assignments (pour un tableau d'objets)<br />
<br />
MAUVAIS : $Quiz <br />
MAUVAIS : $aReallyLongVariableNameWithoutAGoodReason<br />
- MAUVAIS : $error_string</font></p>
- </li>
- <li class="spaced">Les noms des <strong>constantes</strong> doivent toujours
- être en majuscules, et toujours commencer par le nom du module. Les
- mots qui les constituent doivent être séparés par des
- caractères « souligné » (underscore).
- <p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST",
- 1);</font></p>
- </li>
- <li class="spaced">Les noms des <strong>fonctions</strong> doivent être de
- simples mots anglais en minsucules, et commencer avec le nom du module pour
- éviter les conflits entre modules. Les mots qui les constituent
- doivent être séparés par des caractères « souligné » (underscore).
- Les paramètres doivent avoir si possible une valeur par défaut
- sensée. On ne place pas d'espace entre le nom de la fonction et
- la suite (parenthèses)
+ MAUVAIS : $error_string</font></p></li>
+
+<li class="spaced">Les noms des <strong>constantes</strong> doivent toujours être en majuscules, et toujours commencer par le nom du module. Les mots qui les constituent doivent être séparés par des caractères « souligné » (underscore).
+<p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST", 1);</font></p></li>
+
+<li class="spaced">Les noms des <strong>fonctions</strong> doivent être de simples mots anglais en minsucules, et commencer avec le nom du module pour éviter les conflits entre modules. Les mots qui les constituent doivent être séparés par des caractères « souligné » (underscore). Les paramètres doivent avoir si possible une valeur par défaut sensée. On ne place pas d'espace entre le nom de la fonction et la suite (parenthèses)
<p class="examplecode"> <font color="#007700">function </font><font color="#0000BB">forum_set_display_mode</font><font color="#007700">(</font><font color="#0000BB">$mode</font><font color="#007700">=</font><font color="#0000BB">0</font><font color="#007700">)
{<br />
global </font><font color="#0000BB">$USER</font><font color="#007700">,
</font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-></font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br />
}<br />
}</font></p>
- </li>
- <li class="spaced">Les <strong>blocs</strong> doivent toujours être
- placés entre accolades (même s'ils ne sont constitués que d'une ligne).
- Moodle utilise le style suivant :
+</li>
+
+<li class="spaced">Les <strong>blocs</strong> doivent toujours être placés entre accolades (même s'ils ne sont constitués que d'une ligne). Moodle utilise le style suivant :
<p class="examplecode"> <font color="#006600">if (</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
{<br />
if (</font><font color="#0000CC">$numattempts </font><font color="#006600">>
</font><font color="#CC0000">"view.php?id=$cm</font><font color="#006600">-></font><font color="#CC0000">id"</font><font color="#006600">);<br />
}<br />
}</font></p>
- </li>
- <li class="spaced">Les <strong>chaînes de caractères</strong>
- doivent être définies avec des apostrophes droites (pas des
- guillemets) lorsque c'est possible, afin d'améliorer les performances.
+</li>
+
+<li class="spaced">Les <strong>chaînes de caractères</strong> doivent être définies avec des apostrophes droites (pas des guillemets) lorsque c'est possible, afin d'améliorer les performances.
<p class="examplecode"> <font color="#006600">$var = 'some text without any
variables';<br />
$var = "with special characters like a new line \n";<br />
$var = 'a very, very long string with a '.$single.' variable in it';<br />
$var = "some $text with $many variables $within it"; </font></p>
- </li>
- <li class="spaced">Les <strong>commentaires</strong> doivent utiliser
- deux ou trois barres obliques et être alignés avec le code.
+</li>
+
+<li class="spaced">Les <strong>commentaires</strong> doivent utiliser deux ou trois barres obliques et être alignés avec le code.
<p class="examplecode"><font color="#006600">function </font><font color="#0000BB">forum_get_ratings_mean</font><font color="#007700">(</font><font color="#0000BB">$postid</font><font color="#007700">,
</font><font color="#0000BB">$scale</font><font color="#007700">, </font><font color="#0000BB">$ratings</font><font color="#007700">=</font><font color="#0000BB">NULL</font><font color="#007700">)
{<br />
(</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">)
{</font> <br />
... etc. </p>
- </li>
- <li class="spaced">Les <strong>espaces</strong> doivent être
- utilisés généreusement. N'ayez pas peur d'espacer les lignes pour
- accroître la lisibilité. En général, il doit y avoir un espace
- entre les parenthèses et les instructions normales, mais aucun
- espace entre les parenthèses et les variables ou fonctions :
+</li>
+
+<li class="spaced">Les <strong>espaces</strong> doivent être utilisés généreusement. N'ayez pas peur d'espacer les lignes pour accroître la lisibilité. En général, il doit y avoir un espace entre les parenthèses et les instructions normales, mais aucun espace entre les parenthèses et les variables ou fonctions :
<p class="examplecode"> <font color="#007700">foreach (</font><font color="#0000BB">$objects
</font><font color="#007700">as </font><font color="#0000BB">$key </font><font color="#007700">=></font><font color="#0000BB">
$thing</font><font color="#007700">)</font><font color="#006600"> {<br />
</font><font color="#007700">= </font><font color="#0000BB">$d</font><font color="#007700">;</font><font color="#006600"><br />
} </font></p>
</li>
+
</ol>
+
<p> </p>
+
<h2>Structure des bases de données</h2>
+
<ol class="normaltext">
- <li class="spaced">Toutes les tables doit avoir un champ <strong>id</strong>
- (INT10) à incrémentation automatique pour index principal.</li>
- <li class="spaced">La table principale contenant les instances
- de chaque module doit avoir le même nom que le module (par exemple
- <strong>bidule</strong>) et doit contenir au moins les champs
- suivants :
+
+ <li class="spaced">Toutes les tables doit avoir un champ <strong>id</strong> (INT10) à incrémentation automatique pour index principal.</li>
+
+<li class="spaced">La table principale contenant les instances de chaque module doit avoir le même nom que le module (par exemple <strong>bidule</strong>) et doit contenir au moins les champs suivants :
<ul>
<li><strong>id</strong> - voir description ci-dessus</li>
- <li><strong>course</strong> - l'identifiant du cours auquel appartient
- chaque instance</li>
+ <li><strong>course</strong> - l'identifiant du cours auquel appartient chaque instance</li>
<li><strong>name</strong> - le nom complet de chaque instance du module</li>
</ul>
</li>
- <li class="spaced">Les autres tables associées à un module et contenant
- des informations sur des « choses » doivent être appelées
- <strong>bidule_choses</strong> (remarquez le pluriel).</li>
- <li class="spaced">Les noms de colonnes doivent être simples et brefs,
- suivant les mêmes règles que les noms des variables.</li>
- <li class="spaced">Si possible, les colonnes faisant référence
- au champ id d'une autre table (par exemple <strong>bidule</strong>)
- doivent être appelées <strong>widgetid</strong>. (Remarquez que cette
- convention est nouvelle, et n'a pas été suivie dans
- certaines tables plus anciennes.)</li>
- <li class="spaced">Les champs booléens doivent être
- implémentés comme des entiers petits (par exemple INT4)
- contenant 0 ou 1, afin de permettre une éventuelle extension
- des valeurs si nécessaire.</li>
- <li class="spaced">La plupart des tables doivent avoir une champ
- <strong>timemodified</strong> (INT10) qui soit mis à jour
- avec la date et l'heure obtenue avec la fonction PHP
- <strong>time()</strong>.</li>
+
+<li class="spaced">Les autres tables associées à un module et contenant des informations sur des « choses » doivent être appelées <strong>bidule_choses</strong> (remarquez le pluriel).</li>
+
+<li class="spaced">Les noms de colonnes doivent être simples et brefs, suivant les mêmes règles que les noms des variables.</li>
+
+<li class="spaced">Si possible, les colonnes faisant référence au champ id d'une autre table (par exemple <strong>bidule</strong>) doivent être appelées <strong>widgetid</strong>. (Remarquez que cette convention est nouvelle, et n'a pas été suivie dans certaines tables plus anciennes.)</li>
+
+<li class="spaced">Les champs booléens doivent être implémentés comme des entiers petits (par exemple INT4) contenant 0 ou 1, afin de permettre une éventuelle extension des valeurs si nécessaire.</li>
+
+<li class="spaced">La plupart des tables doivent avoir une champ <strong>timemodified</strong> (INT10) qui soit mis à jour avec la date et l'heure obtenue avec la fonction PHP <strong>time()</strong>.</li>
+
</ol>
+
<hr>
+
<p align="center"><font size="1"><a href="." target="_top">Documentation Moodle</a></font></p>
<p align="center"><font size="1">Version: $Id$</font></p>
+
</body>
</html>
projects / moodle.git / commitdiff