Forráskód formázási szabályok

Átírás

1 Forráskód formázási szabályok Írta: Halmai Csongor, Webcenter Bt. A php és html kódrészletek Ugyanazon fájlon belül nem szerepelhet php kód és html tartalom. E kettő különválasztására smarty-t vagy más hasonló sablonkezelő rendszert használunk. A php szakasz jelzésére nem használjuk a <? rövidített jelzést, hanem helyette mindig <?php kerül a fájlokba. <?php => print 1;?> // "<?" Nem helyes! Változók A változókat mindig csupa kisbetűvel írjuk, és aláhúzás jelekkel tagoljuk. Törekedjünk a pontos, önmagyarázó változónevekre! A magyar kifejezéseken kívül a bevett angol kifejezések (set, get, id, stb.) használata is megengedett. $kozlemeny_id Tömb jellegű adatoknál a változónév többes számmal tükrözze azt, hogy több adat van/lehet a változóban: $kozlemeny_idk A konstans értékű változókat csupa nagybetűkkel írjuk: $MAX_FILE_UPLOAD_SIZE Függvények A függvények neve midig kisbetűvel kezdődik, és aláhúzásjelet és számjegyet csak kivételes esetben tartalmazhat (akkor, ha több nagyon hasonló rendeltetésű és nevű fgv. van, és ezek között sorszámmal érdemes különbséget tenni). Kivétel az alól az osztály konstruktora, amelynek kezdőbetűje is nagy. A függvények nevében a tagolást a név belsejébe írt nagybetűk adják. talalatilistamegjelenitese() Függvények nevében a mozaikszavakat csupa nagybetűvel írjuk. 1/5 Webcenter Bt.

2 beolvasottxmlfajlhelyese(); // hibás beolvasottxmlfajlhelyese(); // helyes Osztályok Az osztályok neve megegyezik a konstruktorral, vagyis nagy betűvel kezdődik, és nem tartalmaz aláhúzásjelet, belső nagybetűt azonban esetleg igen. class MyClass extends YourClass {... Kifejezések, zárójelek, szóközök, sorokra tagolás A kifejezések írásakor a szellős írást használjuk. Ez azt jelenti, hogy a zárójeleken belül (a nyitó után és a záró előtt), kerek és szögletes zárójelek esetében is van legalább egy-egy szóköz. Kezdő szögletes zárójel előtt sosincs szóköz. $y = 2 * ( $x[ "a" ][ 1 ] + $x[ "a" ][ 2 ] ) Kezdő kerek zárójel előtt akkor nincs, ha függvény paraméterlistáját határolja, de minden más esetben van. Az értékadó és a feltételes operátorok előtt és után is legalább egy szóköz van. (Lásd a lenti printsign() példát). Kezdő kapcsos zárójel előtt mindig van szóköz, és mindig annak a for(), function(), stb. sornak a végén van, amelyikhez tartozik. function printsign( $x ) { => if ( $x < 0 ) { => => print "-"; => else { => => print ""; => Az include(), include_once(), require(), require_once() utasításoknál a zárójeleket kitesszük. Az if () utasítás mindkét ágát kapcsos zárójelek közé foglaljuk, akkor is, amikor csak egy utasítás van az adott ágban. function printsign( $x ) { => if ( $x < 0 ) { // helyes => => print "-"; => else // helytelen => => print ""; => Utasítások Egy sorba csak egy utasítás kerüljön, még akkor is, ha egyszerű utasításokról van szó. 2/5 Webcenter Bt.

3 //Hibás $x = 0; $y = 1; //Helyes $x = 0; $y = 1; Ne éljünk az egy utasításban elvégezhető többszörös értékadás lehetőségével! //Hibás $x = $y = 0; //Helyes $x = 0; $y = 0; Tabulálás A forráskód minden sora 0, 1 vagy több TAB karakterrel kezdődik, amelyek után nem lehet több TAB a soron belül. A sor elejei TAB-ok számát az határozza meg, hogy az adott utasítás blokkja milyen mélyen van: egy szinttel mélyebb utasítás egy TAB-bal van beljebb. function translatebit( $x ) { => if ( $x == null ) { => => return "NULL"; => => switch ( $x ) { => => case 0: => => => $ret = "nulla"; => => case 1: => => => $ret = "egy"; => => => => default: => => => $ret = "nem bit"; => => return $ret; Az ilyen módon történő tabulálásnak az a célja, hogy ha valaki 4 helyett 2 vagy 8 (vagy bármi más) TAB-szélességet állít be magának, akkor is tökéletesen olvasható marad a program, csak a blokkok behúzása változik a beállítások szerint. Tagolás a sorokon belül TAB karakter csak a sorok elején lehet, az első nem-tab után már nem következhet a sorban újabb TAB, hanem csak szóközök. Szóközök halmozásával érjük el, hogy az egymás alatti értékadások, relációs jelek egymás alá kerüljenek. $x = 1; $long_name = 2; $short = 3; Az olvashatóság érdekében a bonyolultabb kifejezéseket több sorba tagoljuk. Ilyenkor ügyeljünk arra, hogy a TAB-ok csak az adott blokk mélységét jelentik; az ezen túli behúzást a TAB-ok utáni SPACE-ekkel végezzük! 3/5 Webcenter Bt.

4 // helyes: if ( $cond ) { => $x = ( $y1 + 5 > $y2 ) && => ( $my_favourite_var === null ) && => ( $y3 >= $y4 ); // hibás: if ( $cond ) { => $x = ( $y1 + 5 => => => > $y2 ) && => ( $my_favourite_var === null ) && => ( $y3 => => => => >= $y4 ); Megjegyzések (Ez a fejezet a phpdoc-ra áttérés esetén módosulhat) A függvényeket //---- alakú megjegyzés sorokkal határoljuk egymással. A // jel a function kulcsszó f betűje fölött kezdődik, amelyet legalább 40 darab (mínusz) jel követ. A kód megértését segítő megjegyzések // jellel a sorok végén foglalnak helyet. A függvények, osztályok egészét magyarázó megjegyzések a function() illetve a class kulcsszót követő sorban /* és */ jelek között találhatók. class MyClass extends YourClass { => function MyClass() { => => function f1() { => => function f2() { => A megjegyzéseket magyar nyelven, ASCII kódolású ékezetes szöveggel fogalmazzuk meg! if ( $sizeof( $dokumentumok ) >= 3 ) { van //ha elegendő feltöltött dokumentum A függvények deklarációját közvetlenül megelőző sorokban a phpdocumentor által előírt módon írjuk le a függvény fontosabb jellemzőit (lásd /** * Dátumot jelenít meg, a $lang paraméter által meghatározott nyelvi * szabályoknak megfelelően. */ function datum2string( $datum, $lang = "hu" ) { A mit csinál a kódrészlet jellegű magyarázó megjegyzéseknek csak akkor van létjogosultságuk, ha egy nagyobb (pl. >10 sor) kódrész előtt/mögött szerepel. 4/5 Webcenter Bt.

5 // beolvasott adatok feldolgozása foreach ( $adatok as $egy_adat ) {... // beolvasott adatok feldolgozása kész. A kódmagyarázó megjegyzéseknél ne (csak) az szerepeljen, hogy mit csinál a kód, hanem az (is), hogy miért. Nagy, egymásba ágyazott blokkok esetén a bezáró kapcsos zárójelek mögé írt megjegyzéssel utaljunk arra, hogy az a jel mihez tartozik. if () { => foreach ( $adatok as $egy_adat ) { => => while () { => => => => => => => => // while => // foreach // if 5/5 Webcenter Bt.