Linee guida per il programmatore di Moodle

Ogni progetto di tipo collaborativo ha bisogno che coerenza e stabilità siano veramente robuste.

Queste linee guida vogliono rappresentare un riferimento da osservare da parte di tutti i programmi di Moodle. E' vero che parte dei programmi più vecchi non lo rispettano, ma alla fine saranno tutti corretti. Tutta la nuova programmazione deve aderire definitivamente, il più possibile, a questi standard.

Regole generali

  1. Tutti i files contenenti programmi devono usare l'estensione .php.
  2. Tutti i files modello devono usare l'estensione .html.
  3. Tutti i files testo devono usare il formato testo Unix-style (la maggior parte degli editor hanno questa opzione).
  4. Tutti i tag php devono essere tag 'completi' come <?php ?> ... e non tag 'abbreviati' come <? ?>.
  5. Tutte le note di copyright esistenti devono essere mantenute. Potete aggiungerne di vostre ove necessario.
  6. Ogni file deve includere il file principale config.php.
  7. Ogni file deve controllare che l'utente sia autenticato correttamente, usando require_login() e isadmin(), isteacher(), iscreator() oppure isstudent().
  8. Tutti gli accessi ai database devono usare le funzioni presenti in lib/datalib.php, ogni volta che è possibile - questo garantisce la compatibilità con un gran numero di database. Troverete che, usando queste funzioni, è possibile quasi qualunque operazione sui dati. Se dovete scrivere istruzioni SQL, assicuratevi che siano: multi-piattaforma; limitate a funzioni specifiche del vostro programma (di solito un file lib.php); e chiaramente idendificate.
  9. Non create o usate variabili globali ad eccezione di quelle standard $CFG, $SESSION, $THEME e $USER.
  10. Tutte le variabili devono essere inizializzate o almeno la loro esistenza deve essere testata, prima dell'uso, con isset() o empty().
  11. Tutte le stringhe devono essere traducibili - create nuove stringhe nei file in "lang/en" con nomi concisi in inglese e minuscolo e utilizzatele nei vostri programmi tramite get_string() or print_string().
  12. Tutti gli help file devono essere traducibili - create i testi nella cartella "lang/en/help" e richiamateli usando la funzione helpbutton().
  13. I dati inseriti tramite il browser (inviati tramite GET o POST) hanno automaticamente le virgolette applicate (a prescindere dalle impostazioni del PHP) per cui possono essere inseriti direttamente nel database. Tutti gli altri dati (da files, o da database) devono essere "escaped" con addslashes() prima dell'inserimento nel database.

 

Stile di codifica

So che può essere un pò antipatico cambiare il proprio stile, se ne avete uno, ma paragonate, per un momento, questa antipatia con quella di tutte le persone che successivamente cercheranno di capire i programmi di Moodle scritti con stili diversi. Ci sono ovviamente tante buone ragioni a favore e contro ogni stile usato in giro, ma lo stile di Moodle è definito, quindi, per favore, attenetevi strettamente ad esso.

  1. L'indentazione deve essere di 4 spazi. Non usate ASSOLUTAMENTE i tab.
  2. I nomi di variabile devono essere sempre facili da leggere, costituiti da parole in inglese minuscole. Se avete proprio necessità di più di una parola, attaccate le parti, ma sceglietele più corte possibile. Usate nomi plurali per gli "arrays" di oggetti.

    GOOD: $quiz
    GOOD: $errorstring
    GOOD: $assignments (for an array of objects)
    GOOD: $i (but only in little loops)

    BAD: $Quiz
    BAD: $aReallyLongVariableNameWithoutAGoodReason
    BAD: $error_string

  3. Le costanti devono essere sempre maiuscole, e iniziare sempre col nome del modulo. Devono anche avere le parti separate da trattini di sottolineatura.

    define("FORUM_MODE_FLATOLDEST", 1);

  4. I nomi delle funzioni devono essere semplici parole in inglese minuscole, e cominciare col nome del modulo per evitare conflitti tra moduli. Le parti di nome devono essere separate da sottolineature. I parametri devono sempre avere una valore di default, se possibile. Da notare che non c'è alcuno spazio tra il nome della funzione e le (parentesi) che seguono.

    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. I blocchi devono essere sempre racchiusi tra parentesi graffe (anche se c'è solo una riga). Moodle usa questo stile:

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

  6. Le stringhe devono essere definite usando virgolette semplici, ove possibile, per una maggiore velocità.

    $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. I commenti devono usare due o tre barre ed essere ben allineati con le istruzioni.

    function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
    /// Return the mean rating of a post given to the current user by others.
    /// Scale is an array of possible ratings in the scale
    /// Ratings is an optional simple array of actual ratings (just integers)

            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. Gli spazi devono essere usari liberamente - non abbiate paura di sparpagliare un pò le istruzioni per guadagnare in chiarezza. Normalmente, ci dovrebbe essere uno spazio tra le parentesi e le frasi normali, ma nessuno spazio tra le parentesi e le variabili o le funzioni:

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

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

 

Strutture di database

  1. Ogni tabella deve avere un campo id (INT10) ad auto-incremento come indice primario.
  2. La tabella principale contenente le istanze di ogni modulo deve avere lo stesso nome del modulo (per esempio tizio) e contenere almeno i seguenti campi:
  3. Le altre tabelle, associate col modulo, che contengono informazioni su 'cose' si devono chiamare tizio_cose (notare il plurale).
  4. I nomi delle colonne devono essere semplici e corti, e seguire le stesse regole dei nomi delle variabili.
  5. Ove possibile, le colonne che contengono un riferimento al campo 'id' di un'altra tabella (per esempio tizio) si devono chiamare tizioid. (Da notare che questa convenzione è nuova e non è seguita in alcune vecchie tabelle)
  6. I campi Booleani devono essere definiti come campi small integer (per esempio INT4) contenenti 0 o 1, per permettere eventuali future estensioni dei valori.
  7. La maggior parte delle tabelle deve avere un campo (INT10) timemodified che viene aggiornato col timestamp corrente ottenuto dalla funzione PHP time().

Documentazione di Moodle

Version: $Id$