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

Ez a dokumentum a Nette fejlesztésére vonatkozó szabályokat és ajánlásokat írja le. Amikor kódot adsz hozzá a Nette-hez, ezeket be kell tartanod. A legegyszerűbb módja, hogy hogyan lehet ezt megtenni, ha utánozza a meglévő kódot.
Az ötlet lényege, hogy az egész kód úgy nézzen ki, mintha egy személy írta volna. .[perex]

A Nette kódolási szabvány megfelel a [PSR-12 kiterjesztett kódolási stílusnak |https://www.php-fig.org/psr/psr-12/], két fő kivétellel: a behúzásnál [szóközök helyett tabulátorokat |#tabs instead of spaces] használ, és [PascalCase-t |https://blog.nette.org/hu/kevesebb-sikolyert-a-kodban] használ az [osztálykonstansoknál |https://blog.nette.org/hu/kevesebb-sikolyert-a-kodban].


Általános szabályok .[#toc-general-rules]
=========================================

- Minden PHP fájlnak tartalmaznia kell `declare(strict_types=1)`
- Két üres sort használunk a módszerek 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); // @ - directory may exist`
- Ha gyenge tipizált összehasonlító operátort használunk (pl. `==`, `!=`, ...), akkor a szándékot dokumentálni kell: `// == to accept null`
- Több kivételt is írhat egy fájlba `exceptions.php`
- A metódusok láthatósága nincs megadva az interfészek esetében, mivel azok mindig nyilvánosak.
- Minden tulajdonságnak, visszatérési értéknek és paraméternek meg kell adni a típusát. Másrészt a végleges konstansoknál soha nem adjuk meg a típust, mert az nyilvánvaló.
- A karakterlánc elhatárolására szimpla idézőjeleket kell használni, kivéve, ha maga a literál aposztrófokat tartalmaz.


Elnevezési konvenciók .[#toc-naming-conventions]
================================================

- Kerülje a rövidítések használatát, kivéve, ha a teljes név túlzó.
- A kétbetűs rövidítéseknél használjon nagybetűket, a hosszabb rövidítéseknél pedig pascal/camel betűket.
- Használjon főnevet vagy főnévi kifejezést az osztálynévhez.
- Az osztályneveknek nemcsak a specifikusságot (`Array`), hanem az általánosságot (`ArrayIterator`) is tartalmazniuk kell. Kivételt képeznek a PHP attribútumok.
- "Az osztályállandók és enumok PascalCaps-t használjanak":https://blog.nette.org/hu/kevesebb-sikolyert-a-kodban.
- "Az interfészek és absztrakt osztályok nem tartalmazhatnak előtagokat vagy utótagokat":https://blog.nette.org/hu/az-elotagok-es-utotagok-nem-tartoznak-az-interfesznevekbe, mint például `Abstract`, `Interface` vagy `I`.


Bekeretezés és zárójelek .[#toc-wrapping-and-braces]
====================================================

A Nette kódolási szabvány megfelel a PSR-12-nek (vagy PER kódolási stílusnak), néhány ponton jobban meghatározza vagy módosítja azt:

- A nyílfüggvényeket a zárójelek előtt szóköz nélkül írjuk, pl. `fn($a) => $b`
- nincs szükség üres sorra a különböző típusú `use` import utasítások között.
- a függvény/módszer visszatérési típusa és a nyitó szögletes zárójel mindig külön sorban van:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// metódus teste
	}
```

A külön sorban lévő nyitó szögletes zárójel fontos a függvény/módszer aláírásának a testtől való vizuális elválasztásához. Ha az aláírás egy sorban van, a szétválasztás egyértelmű (bal oldali kép), ha több sorban van, a PSR-ben az aláírás és a testek összemosódnak (középen), míg a Nette-szabványban külön maradnak (jobbra):

[* new-line-after.webp *]


Dokumentációs blokkok (phpDoc) .[#toc-documentation-blocks-phpdoc]
==================================================================

A fő szabály: soha ne duplikálj semmilyen aláírás információt, mint például a paraméter típusát vagy a visszatérési típust hozzáadott érték nélkül.

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

- Az osztály leírásával kezdődik.
- Üres sor következik.
- A `@property` (vagy `@property-read`, `@property-write`) megjegyzések soronként következnek. Szintaxis: annotáció, szóköz, típus, szóköz, $név.
- A `@method` megjegyzések soronként következnek. A szintaxis a következő: annotation, space, return type, space, name(type $param, ...).
- A `@author` megjegyzést elhagyjuk. A szerzőséget a forráskód-történetben tartjuk nyilván.
- A `@internal` vagy a `@deprecated` annotáció használható.

```php
/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */
```

A csak `@var` megjegyzést tartalmazó tulajdonság dokumentációs blokkjának egysorosnak kell lennie:

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

Dokumentációs blokk a módszer definíciójához:

- A módszer rövid leírásával kezdődik.
- Nincs üres sor.
- A `@param` megjegyzések, soronként.
- A `@return` megjegyzés.
- A `@throws` megjegyzések, soronként.
- A `@internal` vagy a `@deprecated` megjegyzések használhatók.

Minden megjegyzést egy szóköz követ, kivéve a `@param` megjegyzést, amelyet a jobb olvashatóság érdekében két szóköz követ.

```php
/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array
```


Tabulátorok szóközök helyett .[#toc-tabs-instead-of-spaces]
===========================================================

A tabulátoroknak több előnye is van a szóközökkel szemben:

- A behúzás mérete testre szabható a szerkesztőkben és a "web" -ben:https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size.
- nem kényszerítik rá a felhasználó behúzási méretének preferenciáját a kódra, így a kód jobban hordozható.
- egyetlen billentyűleütéssel beírhatók (bárhol, nem csak a tabulátorokat szóközökké alakító szerkesztőkben).
- a behúzás a céljuk
- tiszteletben tartják a látássérült és vak munkatársak igényeit

Azzal, hogy tabulátorokat használunk a projektjeinkben, lehetővé tesszük a szélesség testreszabását, ami a legtöbb ember számára szükségtelennek tűnhet, de a látássérült emberek számára elengedhetetlen.

A vak programozók számára, akik Braille-kijelzőt használnak, minden egyes szóköz egy Braille-cellával van ábrázolva, és értékes helyet foglal el. Tehát ha az alapértelmezett behúzás 4 szóköz, a 3. szintű behúzás 12 braille-cellát pazarol a kód kezdete előtt.
Egy 40 cellás kijelzőn, amelyet a laptopokon leggyakrabban használnak, ez a rendelkezésre álló cellák több mint egynegyedét jelenti, amelyet információ nélkül elpazarolnak.


{{priority: -1}}