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

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.

  1. Dokumentáció
  2. Legyen Ön is Nette hozzájáruló
  3. Kódolási szabvány