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

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.