Directives pour la programmation

Tout projet o� l'on travaille en collaboration n�cessite une coh�rence et une stabilit� fortes.

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.

R�gles g�n�rales

  1. Tous les fichiers contenant du code doivent avoir l'extension .php.
  2. Tous les fichiers mod�les (� themes �) doivent avoir l'extension .html.
  3. Tous les fichiers en format texte doivent �tre en format Unix (la plupart des �diteurs de texte permettent de convertir les caract�res de fin de ligne).
  4. Toutes les balises php doivent �tre en forme compl�te, comme ceci , et non en forme abr�g�e comme ceci .
  5. Toutes les indications de copyright doivent �tre conserv�es. Vous pouvez ajouter les v�tres au besoin.
  6. Tous les fichiers doivent comporter une commande d'inclusion du fichier config.php principal.
  7. 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() et isstudent().
  8. 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�.
  9. Ne cr�ez et n'utilisez aucune variable globale, sauf les variables standard $CFG, $SESSION, $THEME et $USER.
  10. Toutes les variables doivent �tre initialis�es ou au moins leur existence doit �tre test�e avec isset() ou empty() avant leur utilisation.
  11. 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, courts, en anglais, et utilisez-les dans votre code par l'interm�diaire des fonctions get_string() ou print_string().
  12. Tous les fichiers d'aide doivent �tre traduisibles. Cr�ez-les dans le dossier � lang/en/help � et appelez-les avec la fonction helpbutton().
  13. Les magic_quotes sont automatiquement appliqu�es aux donn�es en provenance du navigateur (envoy�es via GET ou 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 addslashes() avant de les ins�rer dans la base de donn�es.
  14. 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.

 

Style du code

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� dans des styles diff�rents. Bien s�r il y a des avantages et des inconv�nients � chaque style, mais le style de Moodle existe, alors tenez-vous y, s'il vous pla�t.

  1. L'indentation doit �tre de 4 espaces. N'utiliser pas DU TOUT de tabulations.
  2. Les noms des variables doivent toujours �tre des mots anglais en minuscules, faciles � lire et ayant une signification claire. 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.

    BON : $quiz
    BON : $errorstring
    BON : $assignments (pour un tableau d'objets)
    BON : $i (mais seulement dans de petites boucles)

    MAUVAIS : $Quiz
    MAUVAIS : $aReallyLongVariableNameWithoutAGoodReason
    MAUVAIS : $error_string

  3. Les noms des constantes 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).

    define("FORUM_MODE_FLATOLDEST", 1);

  4. Les noms des fonctions doivent �tre de simples mots anglais en minuscules, et commencer par 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)

    function forum_set_display_mode($mode=0) {
        global     $USER, $CFG;

        if (    $mode) {
                $USER->mode = $mode;
        } else if (empty(    $USER->mode)) {
                $USER->mode = $CFG->forum_displaymode;
        }
    }

  5. Les blocs doivent toujours �tre plac�s entre accolades (m�me s'ils ne sont constitu�s que d'une ligne). Moodle utilise le style suivant :

    if ($quiz->attempts) {
        if (    $numattempts > $quiz->attempts) {
                error($strtoomanyattempts, "view.php?id=$cm->id");
        }
    }

  6. Les cha�nes de caract�res doivent �tre d�finies avec des apostrophes droites (pas des guillemets) lorsque c'est possible, afin d'am�liorer les performances.

    $var = 'some text without any variables';
    $var = "with special characters like a new line \n";
    $var = 'a very, very long string with a '.$single.' variable in it';
    $var = "some $text with $many variables $within it";

  7. Les commentaires doivent �tre ajout�s autant que possible, dans le but d'expliciter le fonctionnement du code et le pourquoi des fonctions et variables.

    /**
    * La description doit appara�tre d'abord, avec des ast�risques positionn�s
    * exactement comme dans cet exemple. Pour vous r�f�rer � une autre fonction,
    * utiliser cette syntaxe : {@link clean_param()}. Apr�s la description de la
    * fonction, ajouter celle de chacun des param�tre de la fa�on suivante.
    *
    * @param int $postid Le type PHP est suivi du nom de la variable
    * @param array $scale Le type PHP est suivi du nom de la variable
    * @param array $ratings Le type PHP est suivi du nom de la variable
    * @return mixed
    */
    function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
         if (!$ratings) {
                $ratings = array();     // Initialize the empty array
            if (    $rates = get_records("forum_ratings", "post", $postid)) {
                    // Process each rating in turn
                foreach (    $rates as $rate) {
    ... etc.

  8. Les espaces 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 :

    foreach ($objects as $key => $thing) {
        process($thing);
    }

    if ($x == $y) {
        $a = $b;
    } else if (    $x == $z) {
        $a = $c;
    } else {
        $a = $d;
    }

 

Structure des bases de donn�es

  1. Toutes les tables doivent avoir un champ id (INT10) � incr�mentation automatique pour index principal.
  2. La table principale contenant les instances de chaque module doit avoir le m�me nom que le module (par exemple bidule) et doit contenir au moins les champs suivants :
  3. Les autres tables associ�es � un module et contenant des informations sur des � machins � doivent �tre appel�es bidule_machins (remarquez le pluriel).
  4. Les noms de colonnes doivent �tre simples et courts, suivant les m�mes r�gles que les noms des variables.
  5. Si possible, les colonnes faisant r�f�rence au champ id d'une autre table (par exemple bidule) doivent �tre appel�es biduleid. Cette convention est nouvelle, et n'a pas �t� suivie dans certaines tables plus anciennes.
  6. 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.
  7. La plupart des tables doivent avoir un champ timemodified (INT10) qui soit mis � jour avec la date et l'heure obtenue avec la fonction PHP time().

Probl�mes de s�curit� (et traitement des donn�es des formulaires et des URLs)

  1. Ne vous basez pas sur l'option ��register_globals��. Toutes les variables doivent �tre correctement initialis�es dans tous les fichiers de code. La provenance du nom de la variable doit �tre �vidente.
  2. Initialisez tous les tableaux et tous les objets, m�me lorsqu'ils sont vides. $a = array() ou $obj = new stdClass();.
  3. N'utilisez pas la fonction optional_variable(). Utilisez en lieu et place la fonction optional_param(). Choisissez la valeur PARAM_XXXX correcte pour le type de donn�es que vous attendez. Pour v�rifier et assigner une valeur optionnelle � une variable, utilisez la fonction set_default().
  4. N'utilisez pas la fonction require_variable(). Utilisez en lieu et place la fonction required_param(). Choisissez la valeur PARAM_XXXX correcte pour le type de donn�es que vous attendez.
  5. N'utilisez la fonction data_submitted() qu'avec pr�caution. Avant son utilisation, n'oubliez pas de nettoyer les donn�es.
  6. N'utilisez pas $_GET, $_POST ni $_REQUEST. Utilisez la fonction required_param() ou optional_param() appropri�e � vos besoins.
  7. Ne v�rifiez pas l'ex�cution d'actions avec par exemple if (isset($_GET['something'])). Utilisez plut�t $something = optional_param( 'something',-1,PARAM_INT ) et effectuez ensuite un test correct pour v�rifier si la valeur se trouve dans l'intervalle voulu, par exemple if ($something>=0) {....
  8. Groupez chaque fois que cela est possible vos required_param(), optional_param() et les autres initialisations de variables initialisation au d�but de chaque fichier, de sorte qu'elles soient faciles � trouver.
  9. Utilisez le m�canisme ��sesskey�� pour prot�ger vos routines de traitement de formulaires d'�ventuelles attaques. Un exemple simple : lorsque le formulaire est g�n�r�, ajoutez . Lors du traitement du formulaire, v�rifiez avec if (!confirm_sesskey()) {error('Bad Session Key');}.
  10. Tous les noms de fichiers doivent �tre nettoy�s par la fonction clean_filename(), pour autant que cela n'ait pas encore �t� fait par une utilisation ad�quate de required_param() ou de optional_param().
  11. Toutes les donn�es lues dans la base de donn�es doivent �tre pass�es par addslashes() avant d'�tre r�crites dans la base de donn�es. La fonction addslashes_object() permet de traiter ainsi un objet complet de donn�es.
  12. Chaque fois que c'est possible, les donn�es devant �tre stock�es dans la base de donn�es doivent provenir de donn�es POST (d'un formulaire avec method="POST"), et non de donn�es GET (c'est-�-dire provenant de l'URL).
  13. Si vous pouvez l'�viter, n'utilisez pas de donn�es provenant de la variable $_SERVER, en raison de probl�mes de portabilit�.
  14. Si cela n'a pas �t� fait ailleurs, assurez-vous que toutes les donn�es �crites dans la base de donn�es ont �t� trait�es par la fonction clean_param() avec le param�tre PARAM_XXXX ad�quat au type de donn�es.
  15. Si vous �crivez du code SQL brut, assurez-vous tr�s attentivement qu'il est correct. Faites tout particuli�rement attention aux guillemets manquants autour des valeurs, pouvant se transformer en autant de failles de s�curit� (injections SQL).
  16. V�rifiez toutes les donn�es (particuli�rement celles qui sont �crites dans la base de donn�es) dans tous les fichiers o� elles sont utilis�es. N'attendez rien et ne vous reposez sur rien de ce qui est fait ailleurs.
  17. Les blocs de code � inclure doivent comporter une structure PHP d�finie (par exemple, une d�claration de classe, des d�finitions de fonctions, etc.), Les blocs de code non structur�s engendrent l'utilisation de variables non initialis�es.

Documentation Moodle

Version: $Id$