# Treoirlínte Códúcháin Moodle

Tá comhsheasmhacht agus forastacht riachtanach le go mbeadh aon thionscadal comhoibritheach láidir.

Cuireann na treoirlínte seo sprioc ar fáil d'úsáideoirí cóid Moodle. Is fíor go bhfuil cuid den chód atá ann faoi láthair neamhimleor i roinnt réimsí, ach deiseofar é ar fad ar deireadh. Ní mór do gach códú nua cloí leis na caighdeáin seo chomh fada agus is féidir é.

## Rialacha Ginearálta

1. Ba cheart do gach comhad cóid leas a bhaint as an iarmhír .php.
2. Ba cheart do gach comhad teimpléid leas a bhaint as an iarmhír .html.
3. Ba cheart do gach téacschomhad leas a bhaint as formáid téacs de stíl Unix (tá an rogha seo ar fáil le formhór eagarthóirí téacs).
4. Ní mór do gach clib php a bheith 'iomlán' ar nós <?php ?> ... seachas clibeanna 'gearra' ar nós <? ?>.
5. Ní mór gach fógra cóipchirt a choinneáil. Féadfaidh tú do chuid féin a chur leo más gá.
6. Ba cheart do gach comhad an príomhchomhad config.php a bheith mar chuid de.
7. Ba cheart do gach comhad a sheiceáil go fíordheimhnítear an t-úsáideoir i gceart, trí leas a bhaint as require_login() agus isadmin(), isteacher(), iscreator() nó isstudent().
8. Ba cheart do gach rochtain ar bhunachair sonraí leas a bhaint as na feidhmeanna atá i lib/datalib.php nuair is féidir - ceadaíonn sé seo comhoiriúnach thar réimse leathan bunachar sonraí. Ba cheart go bhfeicfeá gur féidir beagnach gach rud a dhéanamh leis na feidhmeanna seo. Má tá ort cód SQL a scríobh cinntigh: go bhfuil sé trasardáin; srianta go feidhmeanna sonrúla laistigh de do chód (de ghnáth comhad lib.php); agus go bhfuil sé marcáilte go soiléir.
9. Ná cruthaigh agus ná húsáid athróga domhanda seachas cinn caighdeánacha $CFG, $SESSION, $THEME agus $USER.
10. Ba cheart gach athróg a thúsú, nó ar a laghad tástáil gur ann dóibh trí leas a bhaint as isset() nó empty() sula n-úsáidtear iad.
11. Ba cheart do gach teaghrán a bheith inaistrithe - cruthaigh téacsanna nua sna comhaid "lang/en" agus glao orthu trí leas a bhaint as get_string() nó print_string().
12. Ba cheart do gachcomhad cabhrach a bheith inaistrithe - cruthaigh téacsanna nua sa chomhadlann "en/help" agus glao orthu trí leas a bhaint as helpbutton().
13. Cuirtear magic_quotes le sonraí a thagann isteach ón mbrabhsálaí (seolta trí GET nó POST) go huathoibríoch (aineoinn na socruithe PHP) le gur féidir leat é a chur díreach isteach sa bhunachar sonraí go sábháilte. Ní mór gach amhshonra eile (ó chomhaid, nó ó bhunachair sonraí) a éalú le addslashes() sula gcuirtear isteach sa bhunachar sonraí é.

## Stíl Códúcháin

Tá a fhios agam go bhfuil sé beagán achrannach do stíl a athrú má tá cleachtadh agat ar rud ar leith, ach cuir i gcomparáid an t-achrann sin leis an achrann a bheadh i gceist dá mbeadh daoine ag iarraidh bun nó barr a bhaint as cód Moodle dá mbeadh meascán stíleanna ann. Is léir go bhfuil neart buntáistí nó míbhuntáistí le stíleanna a úsáideann daoine éagsúla, ach tá an stíl reatha ann, agus iarraimid ort cloí leis.

1. Eangú: ba cheart 4 spás a bheith ann go seasmhach. Ná bain leas as tábanna AR CHOR AR BITH.
2. Ainmneacha athróige: ba cheart gur focail Bhéarla iad atá éasca le léamh, agus brí leo. Má tá sé iomlán riachtanach go mbeadh níos mó ná focal amháin agat rith le chéile iad, ach coinnigh chomh gairid agus is féidir iad. Úsáid ainmneacha iolra le haghaidh eagair d'oibiachtaí.

   GO MAITH: $quiz
   GO MAITH: $errorstring
   GO MAITH: $assignments (le haghaidh eagar d'oibiachtaí)
   GO MAITH: $i (ach i lúba beaga amháin)
   GO DONA: $Quiz
   GO DONA: $aReallyLongVariableNameWithoutAGoodReason
   GO DONA: $error_string

3. Tairisigh: ba cheart iad a bheith i gceannlitreacha i gcónaí, agus tosú i gcónaí le hainm an mhodúil. Ba cheart na focail a roinnt le fostríoc.

   define("FORUM_MODE_FLATOLDEST", 1);

4. Ainmneacha feidhme: ba cheart gur focail simplí Béarla a bheadh iontu, agus go dtosóidis le hainm an mhodúil le coinbhleacht a sheachaint idir na modúil. Ba cheart focail a roinnt le fostríocanna. Ba cheart réamhshocrú ciallmhar a bheith ag paraiméadair i gcónaí más féidir. Tabhair faoi deara nach bhfuil spás ar bith idir ainm na feidhme agus na (lúibíní) a leanann é.

   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. Blocanna: ní mór iad a chur idir lúibíní 'catacha' (fiú muna bhfuil ann ach líne amháin). Úsáideann Moodle an stíl seo:

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

6. Teaghráin: ba cheart iad a shainmhíniú laistigh de uaschamóga singil nuair is féidir é, ar mhaithe le luas.

   $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. Nótaí tráchta: ba cheart dóibh dhá slais nó trí a úsáid agus teacht le chéile go néata leis an gcód.

   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) {
   ....srl

8. Spás: ba cheart bheith flaithiúil leis - ná bíodh faitíos ort rudaí a scaipeadh amach roinnt éigin ar mhaithe le soiléireacht. Go ginearálta, ba cheart go mbeadh spás amháin idir lúibíní agus gnáth ráitis, agus gan spás ar bith idir lúibíní agus athróga nó feidhmeanna:

   foreach ($objects as $key => $thing) {
   process($thing);
   }
   if ($x == $y) {
   $a = $b;
   } else if ($x == $z) {
   $a = $c;
   } else {
   $a = $d;
   }

## Struchtúr Bunachair Sonraí:

1. Ní mór do gach tábla réimse id (INT10) uath-incriminteach a bheith aige mar innéacs príomhúil.
2. Ní mór don phríomhtábla in dtarlaíonn gach modúl an t-ainm céanna a bheith air is atá ar an modúl (m.sh. widget) agus ar a laghad na réimsí seo a leanas a bheith ann:
   - id - mar a sonraíodh thuas
   - course - id an chúrsa a mbaineann gach ásc leis
   - name - ainm iomlán gach ásc den mhodúl
3. Ba cheart táblaí eile atá gaolmhar le modúl, a bhfuil eolas iontu faoi 'things', ba cheart widget_things a thabhairt orthu (tabhair faoi deara an t-iolra).
4. Ba cheart ainmneacha na gcolún a choinneáil gairid agus simplí, agus na rialacha céanna á leanúint is atá ann d'ainmneacha athróige.
5. Nuair is féidir é, má tá tagairt i gcolún do réimse id i dtábla eile (m.sh. widget), ba cheart widgetid a ghlaoch air. (Tabhair faoi deara gur nós réasúnta nua é seo agus nach leantar é i roinnt sean-táblaí)
6. Ba cheart réimsí Boole a chur i bhfeidhm mar réimsí beaga slánuimhreacha (m.sh. INT4) a bhfuil 0 nó 1 iontu, le leathnú ar luachanna a éascú ar ball más gá.
7. Ba cheart do formhór na dtáblaí réimse timemodified (INT10) a bheith acu a nuashonraítear le ham-stampa reatha trí an bhfeidhm PHP time () a úsáid.

Doiciméid Moodle

Leagan: $Id$