Kódolási szabvány

Ez a dokumentum leírja a Nette fejlesztésére vonatkozó szabályokat és ajánlásokat. Amikor kódot járulsz hozzá a Nette-hez, be kell tartanod őket. Ennek legegyszerűbb módja a meglévő kód utánzása. A lényeg az, hogy minden kód úgy nézzen ki, mintha egyetlen ember írta volna.

A Nette Kódolási Szabvány megfelel a PSR-12 Extended Coding Style-nak, két fő kivétellel: a behúzáshoz tabulátorokat használ szóközök helyett, és az osztály konstansokhoz PascalCase-t használ.

Általános szabályok

• Minden PHP fájlnak tartalmaznia kell a declare(strict_types=1) deklarációt.
• Két üres sort használunk a metódusok elválasztására a jobb olvashatóság érdekében.
• A shut-up operátor használatának okát dokumentálni kell: @mkdir($dir); // @ - a könyvtár létezhet.
• Ha gyengén típusos összehasonlító operátort használunk (pl. ==, !=, …), a szándékot dokumentálni kell: // == elfogadja a null-t
• Egy exceptions.php fájlba több kivételt is írhatsz.
• Az interfészeknél nem adjuk meg a metódusok láthatóságát, mivel azok mindig public-ok.
• Minden property-nek, visszatérési értéknek és paraméternek meg kell adni a típusát. Ezzel szemben a final konstansoknál soha nem adjuk meg a típust, mert az nyilvánvaló.
• A stringek határolására aposztrófokat kell használni, kivéve, ha maga a literál tartalmaz aposztrófokat.

Elnevezési konvenciók

• Ne használj rövidítéseket, hacsak a teljes név nem túl hosszú.
• Kétbetűs rövidítéseknél használj nagybetűket, hosszabb rövidítéseknél pascal/camel case-t.
• Az osztály nevéhez használj főnevet vagy szókapcsolatot.
• Az osztályneveknek nemcsak a specifikusságot (Array), hanem az általánosságot (ArrayIterator) is tartalmazniuk kell. Kivételt képeznek a PHP nyelvi attribútumok.
• Az osztály konstansoknak és enumoknak PascalCaps-t kell használniuk.
• Az interfészeknek és absztrakt osztályoknak nem szabad előtagokat vagy utótagokat tartalmazniuk, mint például Abstract, Interface vagy I.

Tördelés és zárójelek

A Nette Kódolási Szabvány megfelel a PSR-12-nek (illetve a PER Coding Style-nak), néhány pontban kiegészíti vagy módosítja azt:

• az arrow függvényeket szóköz nélkül írjuk a zárójel előtt, azaz fn($a) => $b
• nem szükséges üres sor a különböző típusú use import utasítások között
• a függvény/metódus visszatérési típusa és a nyitó kapcsos zárójel mindig külön sorokban vannak:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// metódus törzse
	}

A nyitó kapcsos zárójel külön sorban fontos a függvény/metódus szignatúrájának és törzsének vizuális elválasztásához. Ha a szignatúra egy sorban van, az elválasztás egyértelmű (bal oldali kép), ha több sorban van, a PSR-ben a szignatúra és a törzs egybefolyik (középen), míg a Nette szabványban továbbra is elkülönülnek (jobbra):

Dokumentációs blokkok (phpDoc)

Fő szabály: Soha ne duplikálj semmilyen információt a szignatúrában, mint például a paraméter típusa vagy a visszatérési típus, hozzáadott érték nélkül.

Dokumentációs blokk egy osztály definíciójához:

• Az osztály leírásával kezdődik.
• Üres sor következik.
• Az @property (vagy @property-read, @property-write) annotációk következnek, egymás után. Szintaxis: annotáció, szóköz, típus, szóköz, $név.
• Az @method annotációk következnek, egymás után. Szintaxis: annotáció, szóköz, visszatérési típus, szóköz, név(típus $param, …).
• Az @author annotációt kihagyjuk. A szerzőiséget a forráskód története őrzi meg.
• Használhatók az @internal vagy @deprecated annotációk.

/**
 * MIME üzenet rész.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Egy property dokumentációs blokkja, amely csak az @var annotációt tartalmazza, egysoros legyen:

/** @var string[] */
private array $name;

Dokumentációs blokk egy metódus definíciójához:

• Rövid metódusleírással kezdődik.
• Nincs üres sor.
• Az @param annotációk külön sorokban.
• Az @return annotáció.
• Az @throws annotációk, egymás után.
• Használhatók az @internal vagy @deprecated annotációk.

Minden annotációt egy szóköz követ, kivéve az @param-ot, amelyet a jobb olvashatóság érdekében két szóköz követ.

/**
 * Fájlt keres egy könyvtárban.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabulátorok szóközök helyett

A tabulátoroknak számos előnyük van a szóközökkel szemben:

• a behúzás mérete a szerkesztőkben és a weben testreszabható
• nem erőltetik a kódra a felhasználó behúzásméret-preferenciáját, így a kód jobban hordozható
• egyetlen billentyűleütéssel írhatók (bárhol, nem csak azokban a szerkesztőkben, amelyek a tabulátorokat szóközökre cserélik)
• a behúzás a céljuk
• tiszteletben tartják a látássérült és vak kollégák igényeit

A tabulátorok használatával projektjeinkben lehetővé tesszük a szélesség testreszabását, ami a legtöbb ember számára feleslegesnek tűnhet, de a látássérültek számára elengedhetetlen.

A Braille-kijelzőket használó vak programozók számára minden szóköz egy Braille-cellát jelent. Tehát ha az alapértelmezett behúzás 4 szóköz, a 3. szintű behúzás 12 értékes Braille-cellát pazarol el még a kód kezdete előtt. Egy 40 cellás kijelzőn, amelyet a laptopoknál leggyakrabban használnak, ez a rendelkezésre álló cellák több mint negyede, amelyet információ nélkül pazarolnak el.