Doiciméid Moodle: Treoirlínte Códúcháin
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
Ba cheart do gach comhad cóid leas a bhaint as an iarmhír .php.
Ba cheart do gach comhad teimpléid leas a bhaint as an iarmhír .html.
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).
Ní mór do gach clib php a bheith 'iomlán' ar nós <?php
?> ... seachas clibeanna 'gearra' ar nós <? ?>.
Ní mór gach fógra cóipchirt a choinneáil. Féadfaidh tú do chuid féin
a chur leo más gá.
Ba cheart do gach comhad an príomhchomhad config.php a bheith mar chuid de.
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().
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.
Ná cruthaigh agus ná húsáid athróga domhanda seachas cinn caighdeánacha
$CFG, $SESSION, $THEME agus $USER.
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.
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().
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().
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.
Eangú: ba cheart 4 spás a bheith ann go seasmhach.
Ná bain leas as tábanna AR CHOR AR BITH.
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
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);
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;
}
}
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");
}
}
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";
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
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í:
Ní mór do gach tábla réimse id (INT10) uath-incriminteach a bheith aige mar innéacs príomhúil.
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
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).
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.
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í)
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á.
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$