Mga Alituntunin sa Pagkokoda 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 koda ng Moodle. May ilang matatandang koda na hindi aabot sa pamantayang ito, pero inaasahan natin na maaayos din ang mga ito sa hinaharap. Ang lahat naman ng bagong koda ay kailangang mahigpit na sumunod sa mga istandard na ito hangga't maaari.

Pangkalahatang Patakaran

  1. Dapat gamitin ng lahat ng sakong koda ang ekstensiyong .php.
  2. Dapat gamitin ng lahat ng sakong padron ang extensiyong .html.
  3. Dapat gamitin ng lahat ng sakong teksto 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 patalastas ng copyright. Maaari kang magdagdag ng sarili mo kung kinakailangan.
  6. Dapat ay naka-include sa bawat sako ang main config.php file.
  7. Dapat tsekin ng bawat sako kung ang tagagamit ay nasino nang wasto, sa pamamagitan ng wastong pagsusuri na has_capability() o required_capability().
  8. Dapat gamitin ng lahat ng pag-access sa mga datosan ang mga function sa lib/datalib.php hangga't maaari - ginagamit ito upang magkaroon ng compatibility sa maraming uri ng datosan. Makikita mo, na posible ang halos lahat ng gusto mong gawin sa pamamagitan ng mga function na ito. Kung kailangan mong magsulat ng SQL koda, tiyakin na ito ay: cross-platform; nakarestrict sa mga partikular na function sa iyong koda (karaniwan ay isang sakong lib.php); at may malinaw na marka.
  9. Huwag kang lilikha o gagamit ng mga global na baryabol maliban na lamang sa istandard na $CFG, $SESSION, $THEME at $USER.
  10. Dapat mainitialise o matest man lamang ang lahat ng baryabol 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" na sako, na may maiigsing pangalan na nasa Ingles at maliit ang titik. Hugutin ang mga string na ito sa koda mo sa pamamagitan ng get_string() o print_string().
  12. Dapat ay maisasalin sa ibang wika ang lahat ng tulong na sako - lumikha ng mga bagong teksto sa "en/help" na direktoryo at icall ito sa pamamagitan ng helpbutton().

    Kung kailangan mong magbago ng isang sakong tulong:

  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 datosan. Lahat ng iba pang raw na datos (mula sa mga sako, o mula sa mga datosan) 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 tagagamit, ay dapat iprint sa pamamagitan ng format_text() na function. Sinisiguro nito na ang teksto ay nasalĂ  at nalinis nang wasto.

 

Estilo ng Pagkokoda

Alam kong medyo nakakainis na magbago ng estilo lalo pa't kung sanay ka na sa sarili mong estilo, pero isipin mo na lang ang pagkainis naman ng ibang tao na naghihirap sa pagbasa ng mga koda ng Moodle 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 gumamit ng mga tab kahit KAILANMAN.
  2. Ang mga pangalan ng baryabol ay dapat na palaging madaling basahin, nasa makahulugang Ingles na salita, at maliit ang titik. 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. Ang mga constant ay dapat na palaging malaki ang mga titik, at nagsisimula palagi sa pangalan ng modyul. Ang mga salita ng mga ito ay dapat pinaghihiwalay ng mga underscore.

    define("FORUM_MODE_FLATOLDEST", 1);

  4. Ang mga pangalan ng function ay dapat na simpleng Ingles na salita na maliit ang titik, at dapat itong magsimula sa pangalan ng modyul para maiwasan ang pagkakagulo ng mga modyul. Ang mga salita ay dapat paghiwalayin ng mga underscore. Dapat ay palaging may makatwirang pinaiiral (default) ang mga parameter, kung maaari. Tandaan na walang space sa pagitan ng pangalan ng function at ng sumusunod ditong (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 datosan

  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 baryabol.
  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 gagawing bago 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 baryabol ay dapat ininitialise nang wasto sa bawat sako ng koda. Kailangan ay kitang-kita kung saan nagmula ang baryabol
  2. I-initialise ang lahat ng array at object, kahit walang laman. $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 baryabol sa simula ng bawat sako, para madali matagpuan ang mga ito.
  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 pangalan ng sako 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 datosan ay dapat idaan sa addslashes() bago ito isulat pabalik sa datosan. 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 datosan 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 datosan 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 kodang SQL, tiyakin na wasto ito. Mag-ingat sa mga nawawalang quote sa palibot ng mga halaga. Posibleng itong maging SQL 'injection' exploit.
  16. Tsekin ang lahat ng datos (lalo na ang isinusulat sa datosan) sa bawat sako na ginagamit ito. Huwag asahan na gagawin ito sa ibang lugar.
  17. Ang mga bloke ng koda na isasama ay dapat mayroong tiyak na balangkas na PHP (hal. class declaration, function definition atbp.) - ang straight na bloke ng koda ay nagpopromote ng dinai-initialise na paggamit ng baryabol.

Dokumentasyon ng Moodle

Version: $Id$