# 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:

    - 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.
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.
   - 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

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:
   - 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
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: coding.html,v 1.1.2.5 2006/02/06 10:00:39 moodler Exp $