Kódolási szabvány
*****************

.[perex]
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 |https://www.php-fig.org/psr/psr-12/]-nak, két fő kivétellel: a behúzáshoz [tabulátorokat használ szóközök helyett |#tabulátory místo mezer], és az ["osztály konstansokhoz PascalCase-t használ" |https://blog.nette.org/cs/za-mene-kriku-v-kodu].


Á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":https://blog.nette.org/cs/za-mene-kriku-v-kodu.
- "Az interfészeknek és absztrakt osztályoknak nem szabad előtagokat vagy utótagokat tartalmazniuk":https://blog.nette.org/cs/predpony-a-pripony-do-nazvu-rozhrani-nepatri, 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:

```php
	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):

[* new-line-after.webp *]


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.

```php
/**
 * 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:

```php
/** @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.

```php
/**
 * 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":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size] 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.


{{priority: -1}}