--- /dev/null
+<html>
+<head>
+<title>Documentation Moodle : Directives pour la programmation</title>
+<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>
+<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"><? ... ?></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 traductibles. Placez-les dans des fichiers de « lang/en » et
+ appelez-les avec les 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>
+</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>
+<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.
+ <p class="examplecode"><font color="#006600">BON : $quiz<br />
+ BON : $errorstring<br />
+ BON : $assignments (pour un tableau d'objets)<br />
+ BON : $i (mais seulement dans de petites boucles)<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, et commencent 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="#0000BB">$CFG</font><font color="#007700">;<br />
+ <br />
+ if (</font><font color="#0000BB">$mode</font><font color="#007700">)
+ {<br />
+ </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
+ </font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br />
+ } else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">))
+ {<br />
+ </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
+ </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 :
+ <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="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
+ {<br />
+ </font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#0000BB">$strtoomanyattempts</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.
+ <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.
+ <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="#FF8000">/// Return the mean rating of a post given
+ to the current user by others.<br />
+ /// Scale is an array of possible ratings in the scale<br />
+ /// Ratings is an optional simple array of actual ratings (just integers)<br />
+ <br />
+ </font><font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">)
+ {<br />
+ </font><font color="#0000BB">$ratings
+ </font><font color="#007700">= array(); </font><font color="#FF8000">//
+ Initialize the empty array</font><font color="#007700"><br />
+ if (</font><font color="#0000BB">$rates
+ </font><font color="#007700">= </font><font color="#0000BB">get_records</font><font color="#007700">(</font><font color="#DD0000">"forum_ratings"</font><font color="#007700">,
+ </font><font color="#DD0000">"post"</font><font color="#007700">, </font><font color="#0000BB">$postid</font><font color="#007700">))
+ {<br />
+ </font><font color="#FF8000">//
+ Process each rating in turn</font><font color="#007700"><br />
+ foreach
+ (</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 :
+ <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">process($thing);</font><font color="#006600">
+ <br />
+ } <br />
+ <br />
+ </font><font color="#007700">if (</font><font color="#0000BB">$x </font><font color="#007700">==
+ </font><font color="#0000BB">$y</font><font color="#007700">)</font><font color="#006600">
+ {<br />
+ </font><font color="#007700"> </font><font color="#0000BB">$a
+ </font><font color="#007700">= </font><font color="#0000BB">$b</font><font color="#007700">;</font><font color="#006600"><br />
+ } else if (</font><font color="#0000BB">$x </font><font color="#007700">==
+ </font><font color="#0000BB">$z</font><font color="#006600">) {<br />
+ </font><font color="#007700"> </font><font color="#0000BB">$a
+ </font><font color="#007700">= </font><font color="#0000BB">$c</font><font color="#007700">;</font><font color="#006600"><br />
+ } else {<br />
+ </font><font color="#007700"> </font><font color="#0000BB">$a
+ </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 :
+ <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>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>
+</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