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.

A Nette kódolási szabvány megfelel a PSR-12 kiterjesztett kódolási stílusnak, két fő kivétellel: a behúzásnál szóközök helyett tabulátorokat használ, és PascalCase-t használ az osztálykonstansoknál.

Általános szabályok

• 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

• 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.
• Az interfészek és absztrakt osztályok nem tartalmazhatnak előtagokat vagy utótagokat, mint például Abstract, Interface vagy I.

Bekeretezés és zárójelek

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:

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

Dokumentációs blokkok (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ó.

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

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

/**
 * 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

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/…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.