Mga Alituntunin sa Pagcode ng Moodle

Alinmang proyekto na pinagtutulungtulungan ng maraming tao ay nangangailangan ng pagiging consistent at stable para manatiling matatag.

Ibinibigay ang mga alituntuning ito para maging pamantayan ng lahat ng code ng Moodle. May ilang matatandang code na hindi aabot sa pamantayang ito, pero inaasahan natin na ma-aayos din ang mga ito sa hinaharap. Ang lahat naman ng bagong code ay kailangang mahigpit na sumunod sa mga istandard na ito hangga't maaari.

Pangkalahatang Patakaran

  1. Dapat gamitin ng lahat ng code file ang ekstensiyong .php.
  2. Dapat gamitin ng lahat ng template file ang extensiong .html.
  3. Dapat gamitin ng lahat ng text file ang estilong-Unix na text format (ang karamihang text editor ay may ganitong option).
  4. Dapat 'full' tag ang gamitin ng lahat ng php tag tulad ng <?php ?> ... sa halip na 'short' tag tulad ng <? ?>.
  5. Dapat panatilihin ang mga umiiral na copyright notice. Maaari kang magdagdag ng sarili mo kung kinakailangan.
  6. Dapat kasama ng bawat file ang main config.php file.
  7. Dapat tsekin ng bawat file kung ang user ay na-authenticate ng wasto, gamit ang require_login() at isadmin(), isteacher(), iscreator() o isstudent().
  8. Dapat gamitin ng lahat ng pag-access sa mga database ang mga function sa lib/datalib.php hangga't maaari - ginagawa nitong magkaroon ng compatibility sa maraming uri ng database. Makikita mo na posible ang halos lahat ng gusto mong gawin sa pamamagitan ng mga function na ito. Kung kailangan mong magsulat ng SQL code, tiyakin na ito ay: cross-platform; nakarestrict sa mga partikular na function sa iyong code (karaniwan ay isang lib.php na file); at may malinaw na marka.
  9. Huwag kang lilikha o gagamit ng mga global variable maliban na lamang sa istandard na $CFG, $SESSION, $THEME at $USER.
  10. Dapat mainitialise o matest man lamang ang lahat ng variable sa pamamagitan ng isset() o empty() bago gamitin ang mga ito.
  11. Dapat ay maisasalin sa ibang wika ang lahat ng string - lumikha ng bagong teksto sa mga "lang/en" file sa maigsing mga Ingles na pangalang nasa lowercase at hugutin ang mga ito mula sa code mo sa pamamagitan ng get_string() o print_string().
  12. Dapat ay maisasalin sa ibang wika ang lahat ng help file - lumikha ng mga bagong teksto sa "en/help" na direktoryo at icall ito sa pamamagitan ng helpbutton().

    Kung kailangan mong mag-update ng isang help file:

  13. Awtomatikong nilalagyan ng magic_quotes (anuman ang kaayusan ng PHP) ang pumapasok na datos mula sa browser (na ipinadala sa pamamagitan ng GET o POST) upang ligtas na maipasok ito nang diretso sa database. Lahat ng iba pang raw na datos (mula sa files, o mula sa mga database) ay kailangang lagyan ng escape sa pamamagitan ng addslashes() bago ipasok sa database.
  14. IMPORTANTE: Lahat ng teksto sa loob ng Moodle, lalo na iyong nagmula sa mga user, ay dapat ipinirint sa pamamagitan ng format_text() na function. Sinisiguro nito na ang teksto ay nafilter at nalinis ng wasto.

 

Estilo ng Pagcocode

Alam kong medyo nakakainis na magbago ng estilo lalo pa't kung sanay ka na sa sarili mo, pero isipin mo na lang ang pagkainis naman ng ibang tao na naghihirap sa pagbasa ng mga Moodle code na iba-iba ang estilo. Mayroon siyempreng kagalingan at kahinaan ang anumang estilo na ginagamit ng mga tao, pero ang kasalukuyang estilo ay hindi na pinagtatalunan kundi basta ito ang estilo, kaya pakisunod naman.

  1. Dapat ay palaging 4 na space ang mga Indent. Huwag gagamit KAILANMAN ng mga tab.
  2. Dapat ay palaging madaling basahin na makahulugang Ingles na salita, na nasa lowercase, ang mga pangalan ng variable. Kung talagang kailangan mo ng higit sa isang salita, pagkabitin ang mga ito, pero panatilihing maigsi hangga't makakaya. Gumamit ng mga plural na pangalan para sa mga array ng mga object.

    TAMA: $quiz
    TAMA: $errorstring
    TAMA: $assignments (para sa isang array ng mga object)
    TAMA: $i (pero gamitin lamang sa maiigsing loop)

    MALI: $Quiz
    MALI: $aReallyLongVariableNameWithoutAGoodReason
    MALI: $error_string

  3. Dapat ay palaging nasa upper case ang mga constant, at magsimula palagi sa pangalan ng modyul. Ang mga salita ng mga ito ay dapat pinaghihiwalay ng mga underscore.

    define("FORUM_MODE_FLATOLDEST", 1);

  4. Dapat ay simpleng Ingles na salita na nasa lowercase ang gagamitin sa mga pangalan ng function, at dapat itong magsimula sa pangalan ng modyul para maiwasan ang pagkakagulo ng mga modyul. Dapat ay palaging may makatwirang default ang mga parameter, kung maaari. Tandaan na walang space sa pagitan ng pangalan ng function at ng sumusunod na (bracket).

    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. Dapat ay palaging nakakulong sa mga curly braces ang mga block (kahit iisang linya lang ito). Ganito ang ginagamit na estilo ng Moodle:

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

  6. Dapat idefine ang mga string sa pamamagitan ng iisang pansipi hangga't maaari, para mapabilis ito.

    $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. Dapat magdagdag ng mga comment hangga't maaari, upang maipaliwanag ang daloy at layunin ng mga function at variable.

    /**
    * The description should be first, with asterisks laid out exactly
    * like this example. If you want to refer to a another function,
    * do it like this: {@link clean_param()}. Then, add descriptions
    * for each parameter as follows.
    *
    * @param int $postid The PHP type is followed by the variable name
    * @param array $scale The PHP type is followed by the variable name
    * @param array $ratings The PHP type is followed by the variable name
    * @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. Dapat gumamit ng maraming space - huwag kang matakot na medyo magkalayo-layo ang mga bagay para mas malinaw itong basahin. Sa pangkalahatan, dapat magkaroon ng isang space sa pagitan ng bawat bracket at mga normal na pahayag, pero walang space sa pagitan ng mga bracket at variable o function:

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

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

 

Mga balangkas ng database

  1. Dapat magka-auto-incrementing id field (INT10) ang bawat table bilang primary na index.
  2. Ang pangunahing table na naglalaman ng mga instance ng bawat modyul ay dapat pangalanan ng parehong pangalan ng modyul (eg widget) at dapat din itong maglaman ng mga sumusunod na minimum na field:
  3. Ang iba pang table na kaugnay ng isang modyul na naglalaman ng impormasyon hinggil sa mga 'things' ay dapat pangalanan ng widget_things (pansinin ang plural).
  4. Dapat maging simple at maigsi ang mga pangalan ng mga column, alinsunod din sa mga alituntunin para sa mga pangalan ng variable.
  5. Kung puwede, dapat tawagin na widgetid ang mga column na may reference sa id field ng isa pang table (eg widget). (Pansinin na medyo bago ang convention na ito at hindi sinusunod sa ilang lumang table)
  6. Dapat i-implement ang mga boolean field bilang mga maliit na integer field (eg INT4) na naglalaman ng 0 o 1, upang makapaglaan ng pagpapalawak ng mga value sa hinaharap kung kakailanganin.
  7. Dapat magka-timemodified field (INT10) ang karamihan sa mga table, na ia-update sa pamamagitan ng kasalukuyang timestamp na nakuha sa pamamgitan ng PHP time() function.

 

Mga Isyu hinggil sa Seguridad (at paghandle ng datos ng form at URL)

  1. Huwag aasa sa 'register_globals'. Ang bawat variable ay dapat ininitialise nang wasto sa bawat code file. Kailangan ay kitang-kita kung saan nagmula ang variable
  2. Iinitialise ang lahat ng array at object, kahit walang lamant. $a = array() o $obj = new stdClass();.
  3. Huwag gagamitin ang optional_variable() na function. Sa halip ay gamitin ang optional_param() na function. Piliin ang wastong halaga na PARAM_XXXX para sa uri ng datos na inaasahan mo. Para matsek at maiset ang isang opsiyonal na halaga para sa isang variable, gamitin ang function na set_default().
  4. Huwag gagamitin ang function na require_variable(). Sa halip ay gamitin ang function na required_param(). Piliin ang wastong halaga na PARAM_XXXX para sa uri ng datos na inaasahan mo.
  5. Ingatan ang paggamit ng data_submitted(). Kailangan munang linisin ang datos bago gamitin
  6. Huwag gagamitin ang $_GET, $_POST o $_REQUEST. Gamitin ang angkop na required_param() o optional_param() na angkop sa pangangailangan mo.
  7. Huwag magtsek ng aksiyon sa pamamagitan ng tulad ng if (isset($_GET['something'])). Gamitin ang e.g., $something = optional_param( 'something',-1,PARAM_INT ) at pagkatapos ay gawin ang angkop na test para matiyak kung nasa inaasahang range ng value ito e.g., if ($something>=0) {....
  8. Hangga't maaari, pangkatin ang lahat ng required_param(), optional_param() mo at iba pang pag-initialise ng variable sa simula ng bawat file, para madali silang matagpuan.
  9. Gumamit ng mekanismong 'sesskey' upang maprotektahan ang mga form handling routine sa mga atake. Payak na halimbawa ng paggamit: kapag nilikha ang form, isama ang <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. Kapag iprinoseso mo ang form tsekin sa pamamagitan ng if (!confirm_sesskey()) {error('Bad Session Key');}.
  10. Kailangang 'linisin' ang lahat ng filename sa pamamagitan ng function na clean_filename(), kung hindi pa ito nagagawa sa pamamagitan ng angkop na paggamit ng required_param() o optional_param()
  11. Ang anumang datos na binasa mula sa database ay dapat idaan sa addslashes() bago ito isulat pabalik sa database. Maaaring tirahin ang isang buong object ng datos sa isang iglap sa pamamagitan ng addslashes_object().
  12. Hangga't maaari, ang datos na iimbakin sa database ay kailangang manggaling sa POST data (mula sa isang fom na may method="POST") sa halip na GET data (ab, datos mula sa URL line).
  13. Huwag gagamitin ang datos mula sa $_SERVER hangga't maiiwasan. May mga suliranin ito sa potability.
  14. Kung hindi pa nagagawa sa ibang lugar, tiyakin na ang lahat ng datos na isinulat sa database ay dumaan sa function na clean_param() sa pamamagitan ng angkop na PARAM_XXXX para sa uri ng datos.
  15. Kung magsusulat ka ng pasadyang SQL code, tiyakin na wasto ito. Mag-ingat sa mga nawawalang quote sa palibot ng mga halaga. Posibleng SQL 'injection' exploit.
  16. Tsekin ang lahat ng datos (lalo na ang isinusulat sa database) sa bawat file na ginagamit ito. Huwag asahan na gagawin ito sa ibang lugar.
  17. Ang mga bloke ng code na isasama ay dapat mayroong tiyak na balangkas na PHP (hal. class declaration, function definition atbp.) - ang straight na bloke ng code ay nagpopromote ng dinaiinitialise na paggamit ng variable.

Dokumentasyon ng Moodle

Version: $Id$