Drupal kódolási stílus

Behúzások és sortörések

Egy behúzás két szóköz méretű, példa:


if (empty($valami)) {
echo "Teljesen be vagyok húzva."
}


A sorok végen ne legyen szóköz, utolsó karakter után legyen új sor. Minden fájl végén legyen egy üres sor: ez azért van, hogyha patchet készítesz, akkor ne kerüljön bele a "\ No newline at end of file" figyelmeztetés, illetve a patch maga olvashatóbb legyen.

Operátorok

Minden bináris operátort (két érték közé helyezendő operátorok), mint például a +, -, =, !=, ==, > stb. egy-egy szóközzel közre kell fogni, hogy olvashatóbb legyen.

Példa: $foo = $bar; (Rosszul írva: $foo=$bar;)

Az egy értékre ható operátorok (mint például az inkrementáló operátor, ++) közvetlenül a változó mellé írandók (pl: $foo++, vagy ++$foo).

Típuskonverzió

Mindig rakj egy szóközt a típus és a változó közé: (int) $mynumber.

Vezérlési szerkezetek (if, for, while, switch, stb.)

Hogy ne legyenek függvényhívásokkal összekeverhetőek az ilyen kódcsoportok, a nyitó parancs (if, else, stb.) után egy szóköz kötelező.

Kapcsos zárójelek használata minden esetben javasolt, még akkor is, ha a kód maga értelmes lenne nélkülük (egy soros mag). Ettől javul az olvashatóság, és valamelyest csökkenti annak esélyét, hogy a kódmag bővítése során logikai hibák kerüljenek be.


if (condition1 || condition2) {
action1;
}
elseif (condition3 && condition4) {
action2;
}
else {
defaultaction;
}


Függvényhívások és függvénydefiníciók

Függvények hívásakor a függvény neve és az argumentumok nyitó zárójele közé nem szabad szóközt tenni, illetve – mint minden felsorolás jellegű kódrészletben – a vessző és a következő paraméter közé kell a szóköz. Az utolsó paraméter után közvetlenül jön a zárójel és a kódsor végét jelző pontosvessző.


$var = foo($bar, $baz, $quux);


Ahogy látszik, az egyenlőségjel két oldalán van egy-egy szóköz, ahogy a függvény visszatérési értékét hozzárendeljük a változóhoz. Egymás után több érték változóhoz rendelése esetén több szóközt is beszúrhatunk a kód jobb olvashatósága érdekében:


$short = foo($bar);
$long_variable = foo($baz);


Azok az argumentumok, amelyeknek van alapértelmezett értékük, az argumentum-lista végére kell, hogy kerüljenek. Törekedj értelmes visszatérési érték meghatározására, ha lehetséges.

Tömbök

Tömbelemek egymástól a szokásos felsorolás stílusban (egy vessző, utána szóköz) írandóak. Amennyiben kulcs hozzárendelést alkalmazunk (=>), akkor az operátor elé és mögé is írandó szóköz:

$some_array = array('hello', 'world', 'foo' => 'bar');

Ha egy ilyen tömb-sor hosszabb lenne 80 karakternél (ami elég gyakran előfordul, például űrlap, illetve menü definícióknál), akkor a tömbelemek soronként írandóak, egy behúzással (azaz két szóközzel):


$form['title'] = array(
'#type' => 'textfield',
'#title' => t('Title'),
'#size' => 60,
'#maxlength' => 128,
'#description' => t('The title of your node.'),
);


Érdemes megfigyelni, hogy az utolsó sor végén is van egy vessző. Ez nem elírás, ez a jelölésmód segít későbbi feldolgozási hibák elkerülésében, ha bővitjuk a listát.

Idézetek

A kettős, vagy szimpla idézőjelek használatáról nincsen kőbe vésett szabály a Drupalban. Ahol lehetséges, próbálj törekedni az adott modul írásmódjával egybeesően írni: tiszteld a többi programozó egyeni stílusát.
Ugyanakkor érdemes fejben tartani, hogy a szimpla idézőjeleket gyorsabban értelmezi a PHP, mert nem próbál változókat keresni a sorban (például: "


$header

"

). Ezenkívül fordítandó szöveg esetén is ajánlott kettős idézőjelet használni, ha maga a szöveg tartalmazna szimpla idézőjelet (ekkor ugyanis egy az idézőjel elé egy visszaperjel írandó, amit a .pot készítő nem biztos, hogy meg tud oldani).

Sztring összefűzés

Mindig rakj szóközt a pont és az összefűzendő változók, értékek közé, ez nagyban javítja az olvashatóságot.

$string = 'Foo' . $bar;
$string = $bar . 'foo';
$string = bar() . 'foo';
$string = 'foo' . 'bar';
?>

Egyszerű változók esetén szabad dupla idézőjelet használni, és a változót közvetlenül az idézeten belül kiírni:

$string = "Foo $bar";
?>

Ha az összefűzés a saját operátora által ('.=') történik, akkor (mint ahogy korábban írtuk az operátorok esetén) mindkét oldalról egy szóközzel kell közrevenni:

$string .= 'Foo';
$string .= $bar;
$string .= baz();
?>

Megjegyzések

Sorbeli forrás dokumentáció a Doxygen formázási szabályokat követi.
Ajánlott nem dokumentáció jellegű megjegyzésekkel bővíteni a kódot. Nagy általánosságban az olyan programrészletek, amik megírása után az ember legszívesebben zacskót húzna a fejére és elmenekülne dél-Indiába, azonnal dokumentálandóak, mielőtt elfelejti a szerző, hogy mit és hogyan és miért úgy csinált.

Nem dokumentálás jellegű megjegyzéseknek is nyelvtanilag helyes, teljes mondatoknak kell lenniük (nagy betűvel kezdődően, mondat végén pont, mondatok egy szóközzel elválasztva). Csupa nagybetűt csak akkor használunk, ha állandókra (például TRUE) hivatkozunk. Megjegyzések külön sorba írandóak, közvetlenül a vonatkozó kódrészlet elé, például:


// Unselect all other contact categories.
db_query('UPDATE {contact} SET selected = 0');


Ha egy lista elemeihez fűznénk magyarázatot, akkor írhatunk ugyanabba a sorba, sőt be is húzhatjuk, hogy olvashatóbbak legyenek a megjegyzések.
Mind a C-ben használt megjegyzés stílus (/* */) és a C++ féle (//) elfogadott, Perl, illetve shell típusú # megjegyzések kerülendőek.

Kód include-olása

Ahol feltétel nélkül kell egy PHP kódot tartalmazó fájlt meghívni, ott használj require_once()-t. Ahol ez feltételhez van kötve, ott include_once() használatos. Ez a két utasítás közös fájllistát kezel, vagyis ugyanaz a fájl nem lesz kétszer meghívva.

Miután az include_once() es a require_once() nem függvény, hanem nyelvi elem (statement), ezért nem kell a fájlnév köré zárójelet tenni.

Ha ugyanabból a könyvtárból, vagy alkönyvtárból hívunk fájlt, az elérési utat kezdjük "."-vel: include_once ./includes/mymodule_formatting.inc. Drupal 7.x alatt használjuk a DRUPAL_ROOT állandót: require_once DRUPAL_ROOT . '/' . variable_get('cache_inc', 'includes/cache.inc');

PHP kód jelölők

Mindig a tageket használd PHP kód írásakor, a rövidebb ?> helyett. Ez nem csak Drupal standard miatt van így, hanem a kód hordozhatósága miatt is nagyon fontos, eltérő szerver konfigurációk esetenként tilthatják a rövidebb jelölést.

Pontosvesszők

A PHP nyelv szintaxisa megköveteli a sor végi pontosvesszőt, viszont megengedi annak elhagyását kód blokkok esetén. A Drupal kódolási stílusa viszont még ott is megköveteli:
Helyes:
Helytelen:

Forrás: http://drupal.org/coding-standards
Ez a fordítás közösségi munka eredménye, ha bármi hibát találsz, vagy szebben meg tudnád fogalmazni, akkor segíts javítani.