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

Dapat gamitin ng lahat ng code file ang ekstensiyong .php.
Dapat gamitin ng lahat ng template file ang extensiong .html.
Dapat gamitin ng lahat ng text file ang Unix-style na text format (ang karamihang text editor ay may ganitong option).
Dapat 'full' tag ang gamitin ng lahat ng php tag tulad ng <?php ?> ... sa halip na 'short' tag tulad ng <? ?>.
Dapat panatilihin ang mga copyright notice. Maaari kang magdagdag ng sarili mo kung kinakailangan.
Dapat kasama ng bawat file ang main config.php file.
Dapat tsekin ng bawat file kung ang user ay na-authenticate ng wasto, gamit ang require_login() at isadmin(), isteacher(), iscreator() o isstudent().
Dapat gamitin ng lahat ng pagaccess 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.
Huwag kang lilikha o gagamit ng mga global variable maliban na lamang sa istandard na $CFG, $SESSION, $THEME at $USER.
Dapat mainitialise o matest man lamang ang lahat ng variable sa pamamagitan ng isset() o empty() bago gamitin ang mga ito.
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().
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:
- kung may kaunting pagbabago, at ang lumang salin ng file ay mauunawaan pa rin, OK lang na baguhin ito pero kailangan mong pasabihan ang translation@moodle.org
- kung may malaking pagbabago, dapat ay lumikha ka ng bagong file sa pamamagitan ng pagdaragdag ng incrementing na bilang (eg filename2.html), para makita agad ng mga tagasalin na bagong bersiyon ito ng file. Siyempre ang bagong code at ang mga help index file ay kailangan ding baguhin upang tumuro sa mga pinakabagong bersiyon.
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.
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.

Dapat ay palaging 4 na space ang mga Indent. Huwag gagamit KAILANMAN ng mga tab.
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
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);
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;
    }
}
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");
    }
}
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";
Dapat magdagdag ng mga comment hangga't maaari, upang maipaliwanag ang daloy at layunin ng mga function at variable.
- Ang bawat function (at class) ay dapat gamitan ng popular na phpDoc format. Pinapahintulutan nito ang awtomatikong paglikha ng dokumentasyon ng code.
- Ang mga inline na comment ay dapat gamitan ng estilong // , na ihinanay nang maayos upang umangkop ito sa code at umayon ito sa linya nito.
/**
* 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
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

Dapat magka-auto-incrementing id field (INT10) ang bawat table bilang primary na index.
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:
- id - ayon sa pagkakalarawan sa itaas
- course - ang id ng kurso kung saan nabibilang ang bawat instance
- name - ang buong pangalan ng bawat instance ng modyul
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).
Dapat maging simple at maigsi ang mga pangalan ng mga column, alinsunod din sa mga alituntunin para sa mga pangalan ng variable.
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)
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.
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.

Dokumentasyon ng Moodle

Version: $Id$