<commit_before><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<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>

<h1>Directives pour la programmation</h1>

<p class="normaltext">Tout projet o&ugrave; l'on travaille en collaboration n&eacute;cessite une coh&eacute;rence et une stabilit&eacute; fortes.</p>

<p class="normaltext">L'objectif de ces directives est de fournir un cadre &agrave; respecter pour tout le code de Moodle. Il est vrai que certaines parties plus anciennes du code ne les respectent pas toujours&nbsp;; le code sera corrig&eacute;. Tout le nouveau code doit absolument respecter ces directives aussi pr&eacute;cis&eacute;ment que possible.</p>

<h2>R&egrave;gles g&eacute;n&eacute;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&egrave;les (&laquo;&nbsp;themes&nbsp;&raquo;) doivent avoir l'extension .html.</li>

<li class="spaced">Tous les fichiers en format texte doivent &ecirc;tre en format Unix (la plupart des &eacute;diteurs de texte permettent de convertir les caract&egrave;res de fin de ligne).</li>

<li class="spaced">Toutes les balises php doivent &ecirc;tre en forme compl&egrave;te, comme ceci <font color="#339900">&lt;?php ... ?&gt;</font>, et non en forme abr&eacute;g&eacute;e comme ceci <font color="#339900">&lt;?php  ... ?&gt;</font>.</li>

<li class="spaced">Toutes les indications de copyright doivent &ecirc;tre conserv&eacute;es. Vous pouvez ajouter les v&ocirc;tres au besoin.</li>

<li class="spaced">Tous les fichiers doivent comporter une commande d'inclusion du fichier config.php principal.</li>

<li class="spaced">Tous les fichiers doivent v&eacute;rifier que l'utilisateur est correctement authentifi&eacute;, &agrave; l'aide de require_login() et d'une des fonctions isadmin(), isteacher(), iscreator() et isstudent().</li>

<li class="spaced">Tous les acc&egrave;s aux bases de donn&eacute;es doivent autant que possible utiliser les fonctions d&eacute;finies dans lib/datalib.php. Ceci permet la compatibilit&eacute; avec un grand nombre de marques de bases de donn&eacute;es. Il est possible de faire presque tout avec ces fonctions. Si vous devez &eacute;crire du code SQL, assurez-vous qu'il soit&nbsp;: multi-plateforme, restreint &agrave; des fonctions sp&eacute;cifiques de votre code (habituellement plac&eacute;s dans un fichier lib.php) et clairement marqu&eacute;.</li>

<li class="spaced">Ne cr&eacute;ez et n'utilisez aucune variable globale, sauf les variables standard $CFG, $SESSION, $THEME et $USER.</li>

<li class="spaced">Toutes les variables doivent &ecirc;tre initialis&eacute;es ou au moins leur existence doit &ecirc;tre test&eacute;e avec isset() ou empty() avant leur utilisation.</li>

<li class="spaced">Toutes les cha&icirc;nes de caract&egrave;res doivent &ecirc;tre traduisibles. Cr&eacute;ez les nouvelles cha&icirc;nes dans les fichiers du dossier &laquo;&nbsp;lang/en&nbsp;&raquo;, donnez-leur des noms en minuscules, courts, en anglais, et utilisez-les dans votre code par l'interm&eacute;diaire des fonctions get_string() ou print_string().</li>

<li class="spaced">Tous les fichiers d'aide doivent &ecirc;tre traduisibles. Cr&eacute;ez-les dans le dossier &laquo;&nbsp;lang/en/help&nbsp;&raquo; et appelez-les avec la fonction helpbutton().</li>

<li class="spaced">Les magic_quotes sont automatiquement appliqu&eacute;es aux donn&eacute;es en provenance du navigateur (envoy&eacute;es via GET ou POST), ind&eacute;pendamment des r&eacute;glages de PHP. Il est donc s&ucirc;r de les ins&eacute;rer directement dans la base de donn&eacute;es. Toutes les autres donn&eacute;es brutes (en provenance de fichiers ou de bases de donn&eacute;es) doivent &ecirc;tre encod&eacute;es avec <font color="#339900">addslashes()</font> avant de les ins&eacute;rer dans la base de donn&eacute;es.</li>

<li class="spaced">IMPORTANT : tous les textes dans Moodle, tout particuli&egrave;rement ceux qui proviennent des utilisateurs, doivent &ecirc;tre affich&eacute;s &agrave; l'aide de la fonction format_text(). Ceci permet de s'assurer que le texte est filtr&eacute; et nettoy&eacute; correctement.</li>

</ol>

<p>&nbsp;</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&ecirc;tement avec les gros ennuis qu'ont ult&eacute;rieurement les personnes qui essaient de comprendre un code compos&eacute; dans des styles diff&eacute;rents. Bien s&ucirc;r il y a des avantages et des inconv&eacute;nients &agrave; chaque style, mais le style de Moodle <strong>existe</strong>, alors tenez-vous y, s'il vous pla&icirc;t.</p>

<ol class="normaltext">

<li class="spaced">L'<strong>indentation</strong> doit &ecirc;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 &ecirc;tre des mots anglais en minuscules, faciles &agrave; lire et ayant une signification claire. Si vous avez vraiment besoin de plusieurs mots, concat&eacute;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 &ecirc;tre en majuscules, et toujours commencer par le nom du module. Les mots qui les constituent doivent &ecirc;tre s&eacute;par&eacute;s par des caract&egrave;res &laquo;&nbsp;soulign&eacute;&nbsp;&raquo; (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 &ecirc;tre de simples mots anglais en minuscules, et commencer par le nom du module, pour &eacute;viter les conflits entre modules. Les mots qui les constituent doivent &ecirc;tre s&eacute;par&eacute;s par des caract&egrave;res &laquo;&nbsp;soulign&eacute;&nbsp;&raquo; (underscore). Les param&egrave;tres doivent avoir si possible une valeur par d&eacute;faut sens&eacute;e. On ne place pas d'espace entre le nom de la fonction et la suite (parenth&egrave;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;global </font><font color="#0000BB">$USER</font><font color="#007700">, 
      </font><font color="#0000BB">$CFG</font><font color="#007700">;<br />
      <br />
      &nbsp;&nbsp;&nbsp;&nbsp;if (</font><font color="#0000BB">$mode</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;} else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">)) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
</li>

<li class="spaced">Les <strong>blocs</strong> doivent toujours &ecirc;tre plac&eacute;s entre accolades (m&ecirc;me s'ils ne sont constitu&eacute;s que d'une ligne). Moodle utilise le style suivant&nbsp;:
    <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 />
      &nbsp;&nbsp;&nbsp;&nbsp;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
</li>

<li class="spaced">Les <strong>cha&icirc;nes de caract&egrave;res</strong> doivent &ecirc;tre d&eacute;finies avec des apostrophes droites (pas des guillemets) lorsque c'est possible, afin d'am&eacute;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 &ecirc;tre align&eacute;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$ratings 
      </font><font color="#007700">= array(); &nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Initialize the empty array</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Process each rating in turn</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foreach 
      (</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">) 
      {</font> <br />
      ... etc. </p><commit_msg>Added information about phpdoc<commit_after><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<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>

<h1>Directives pour la programmation</h1>

<p class="normaltext">Tout projet o&ugrave; l'on travaille en collaboration n&eacute;cessite une coh&eacute;rence et une stabilit&eacute; fortes.</p>

<p class="normaltext">L'objectif de ces directives est de fournir un cadre &agrave; respecter pour tout le code de Moodle. Il est vrai que certaines parties plus anciennes du code ne les respectent pas toujours&nbsp;; le code sera corrig&eacute;. Tout le nouveau code doit absolument respecter ces directives aussi pr&eacute;cis&eacute;ment que possible.</p>

<h2>R&egrave;gles g&eacute;n&eacute;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&egrave;les (&laquo;&nbsp;themes&nbsp;&raquo;) doivent avoir l'extension .html.</li>

<li class="spaced">Tous les fichiers en format texte doivent &ecirc;tre en format Unix (la plupart des &eacute;diteurs de texte permettent de convertir les caract&egrave;res de fin de ligne).</li>

<li class="spaced">Toutes les balises php doivent &ecirc;tre en forme compl&egrave;te, comme ceci <font color="#339900">&lt;?php ... ?&gt;</font>, et non en forme abr&eacute;g&eacute;e comme ceci <font color="#339900">&lt;?php  ... ?&gt;</font>.</li>

<li class="spaced">Toutes les indications de copyright doivent &ecirc;tre conserv&eacute;es. Vous pouvez ajouter les v&ocirc;tres au besoin.</li>

<li class="spaced">Tous les fichiers doivent comporter une commande d'inclusion du fichier config.php principal.</li>

<li class="spaced">Tous les fichiers doivent v&eacute;rifier que l'utilisateur est correctement authentifi&eacute;, &agrave; l'aide de require_login() et d'une des fonctions isadmin(), isteacher(), iscreator() et isstudent().</li>

<li class="spaced">Tous les acc&egrave;s aux bases de donn&eacute;es doivent autant que possible utiliser les fonctions d&eacute;finies dans lib/datalib.php. Ceci permet la compatibilit&eacute; avec un grand nombre de marques de bases de donn&eacute;es. Il est possible de faire presque tout avec ces fonctions. Si vous devez &eacute;crire du code SQL, assurez-vous qu'il soit&nbsp;: multi-plateforme, restreint &agrave; des fonctions sp&eacute;cifiques de votre code (habituellement plac&eacute;s dans un fichier lib.php) et clairement marqu&eacute;.</li>

<li class="spaced">Ne cr&eacute;ez et n'utilisez aucune variable globale, sauf les variables standard $CFG, $SESSION, $THEME et $USER.</li>

<li class="spaced">Toutes les variables doivent &ecirc;tre initialis&eacute;es ou au moins leur existence doit &ecirc;tre test&eacute;e avec isset() ou empty() avant leur utilisation.</li>

<li class="spaced">Toutes les cha&icirc;nes de caract&egrave;res doivent &ecirc;tre traduisibles. Cr&eacute;ez les nouvelles cha&icirc;nes dans les fichiers du dossier &laquo;&nbsp;lang/en&nbsp;&raquo;, donnez-leur des noms en minuscules, courts, en anglais, et utilisez-les dans votre code par l'interm&eacute;diaire des fonctions get_string() ou print_string().</li>

<li class="spaced">Tous les fichiers d'aide doivent &ecirc;tre traduisibles. Cr&eacute;ez-les dans le dossier &laquo;&nbsp;lang/en/help&nbsp;&raquo; et appelez-les avec la fonction helpbutton().</li>

<li class="spaced">Les magic_quotes sont automatiquement appliqu&eacute;es aux donn&eacute;es en provenance du navigateur (envoy&eacute;es via GET ou POST), ind&eacute;pendamment des r&eacute;glages de PHP. Il est donc s&ucirc;r de les ins&eacute;rer directement dans la base de donn&eacute;es. Toutes les autres donn&eacute;es brutes (en provenance de fichiers ou de bases de donn&eacute;es) doivent &ecirc;tre encod&eacute;es avec <font color="#339900">addslashes()</font> avant de les ins&eacute;rer dans la base de donn&eacute;es.</li>

<li class="spaced">IMPORTANT : tous les textes dans Moodle, tout particuli&egrave;rement ceux qui proviennent des utilisateurs, doivent &ecirc;tre affich&eacute;s &agrave; l'aide de la fonction format_text(). Ceci permet de s'assurer que le texte est filtr&eacute; et nettoy&eacute; correctement.</li>

</ol>

<p>&nbsp;</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&ecirc;tement avec les gros ennuis qu'ont ult&eacute;rieurement les personnes qui essaient de comprendre un code compos&eacute; dans des styles diff&eacute;rents. Bien s&ucirc;r il y a des avantages et des inconv&eacute;nients &agrave; chaque style, mais le style de Moodle <strong>existe</strong>, alors tenez-vous y, s'il vous pla&icirc;t.</p>

<ol class="normaltext">

<li class="spaced">L'<strong>indentation</strong> doit &ecirc;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 &ecirc;tre des mots anglais en minuscules, faciles &agrave; lire et ayant une signification claire. Si vous avez vraiment besoin de plusieurs mots, concat&eacute;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 &ecirc;tre en majuscules, et toujours commencer par le nom du module. Les mots qui les constituent doivent &ecirc;tre s&eacute;par&eacute;s par des caract&egrave;res &laquo;&nbsp;soulign&eacute;&nbsp;&raquo; (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 &ecirc;tre de simples mots anglais en minuscules, et commencer par le nom du module, pour &eacute;viter les conflits entre modules. Les mots qui les constituent doivent &ecirc;tre s&eacute;par&eacute;s par des caract&egrave;res &laquo;&nbsp;soulign&eacute;&nbsp;&raquo; (underscore). Les param&egrave;tres doivent avoir si possible une valeur par d&eacute;faut sens&eacute;e. On ne place pas d'espace entre le nom de la fonction et la suite (parenth&egrave;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;global </font><font color="#0000BB">$USER</font><font color="#007700">, 
      </font><font color="#0000BB">$CFG</font><font color="#007700">;<br />
      <br />
      &nbsp;&nbsp;&nbsp;&nbsp;if (</font><font color="#0000BB">$mode</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;} else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">)) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
</li>

<li class="spaced">Les <strong>blocs</strong> doivent toujours &ecirc;tre plac&eacute;s entre accolades (m&ecirc;me s'ils ne sont constitu&eacute;s que d'une ligne). Moodle utilise le style suivant&nbsp;:
    <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 />
      &nbsp;&nbsp;&nbsp;&nbsp;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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 />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
</li>

<li class="spaced">Les <strong>cha&icirc;nes de caract&egrave;res</strong> doivent &ecirc;tre d&eacute;finies avec des apostrophes droites (pas des guillemets) lorsque c'est possible, afin d'am&eacute;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 tre ajouts autant que possible, dans le but d'expliciter le fonctionnement du code et le pourquoi des fonctions et variables.
    <ul>
       <li>Toutes les fonctions (et les classes) doivent utiliser le format trs rpandu <a target="_blank" href="http://www.phpdoc.org/">phpDoc</a>, qui permet la gnration automatique de la documentation du code.</li>
       <li>Dans le code lui-mme, il convient d'utiliser le style //, formatt proprement, de sorte que les commentaires soient bien ajusts et aligns avec le code.</li>
    </ul>
    <p class="examplecode"><font color="#ff8800">
  	 /**<br />
  	  * La description doit apparatre d'abord, avec des astrisques positionns<br />
  	  * exactement comme dans cet exemple. Pour vous rfrer  une autre fonction,<br />
  	  * utiliser cette syntaxe : {@link clean_param()}. Aprs la description de la<br />
  	  * fonction, ajouter celle de chacun des paramtre de la faon suivante.<br />
  	  *<br />
  	  * @param int    $postid Le type PHP est suivi du nom de la variable<br />
  	  * @param array  $scale Le type PHP est suivi du nom de la variable<br />
  	  * @param array  $ratings Le type PHP est suivi du nom de la variable<br />
  	  * @return mixed<br />
  	  */</font><br />
<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>
      &nbsp;&nbsp;&nbsp;&nbsp;<font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$ratings 
      </font><font color="#007700">= array(); &nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Initialize the empty array</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Process each rating in turn</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foreach 
      (</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">) 
      {</font> <br />
      ... etc. </p>
{'fraction_non_alphanumeric': 0.17386268322882134, 'fraction_numerical': 0.039062187961816514, 'mean_word_length': 5.585481325618096, 'pattern_counts': {'":': 0, '<': 640, '<?xml version=': 0, '>': 656, 'https://': 0, 'lorem ipsum': 0, 'www.': 5, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4004547', 'n_tokens_mistral': 9408, 'n_tokens_neox': 8490, 'n_words': 2211}