Standard kodiranja

Ta dokument opisuje pravila in priporočila za razvoj Nette. Pri prispevanju kode k Nette jih morate upoštevati. Najlažji način za to je posnemanje obstoječe kode. Gre za to, da vsa koda izgleda, kot da jo je napisala ena oseba.

Nette Coding Standard ustreza PSR-12 Extended Coding Style z dvema glavnima izjemama: za zamikanje uporablja zavihke namesto presledkov in za konstante razredov uporablja PascalCase.

Splošna pravila

• Vsaka PHP datoteka mora vsebovati declare(strict_types=1)
• Dve prazni vrstici se uporabljata za ločevanje metod za boljšo berljivost.
• Razlog za uporabo operatorja za utišanje (shut-up operator) mora biti dokumentiran: @mkdir($dir); // @ - mapa lahko obstaja.
• Če je uporabljen šibko tipiziran primerjalni operator (tj. ==, !=, …), mora biti namen dokumentiran: // == sprejmi null
• V eno datoteko exceptions.php lahko zapišete več izjem.
• Pri vmesnikih se ne določa vidnost metod, ker so vedno javne.
• Vsaka lastnost, vrnjena vrednost in parameter morajo imeti naveden tip. Nasprotno pa pri končnih konstantah tipa nikoli ne navajamo, ker je očiten.
• Za omejevanje niza naj se uporabljajo enojni narekovaji, razen v primerih, ko sam literal vsebuje apostrofe.

Poimenovalne konvencije

• Ne uporabljajte okrajšav, razen če je celotno ime predolgo.
• Pri dvočrkovnih okrajšavah uporabljajte velike črke, pri daljših okrajšavah pascal/camel.
• Za ime razreda uporabljajte samostalnik ali besedno zvezo.
• Imena razredov morajo vsebovati ne samo specifičnost (Array), ampak tudi splošnost (ArrayIterator). Izjema so atributi jezika PHP.
• Konstante razredov in enumeracije naj uporabljajo PascalCaps.
• Vmesniki in abstraktni razredi ne smejo vsebovati predpon ali pripon kot Abstract, Interface ali I.

Wrapping and Braces

Nette Coding Standard ustreza PSR-12 (oz. PER Coding Style), v nekaterih točkah ga dopolnjuje ali spreminja:

• puščične funkcije se pišejo brez presledka pred oklepajem, tj. fn($a) => $b
• ne zahteva se prazna vrstica med različnimi tipi use import stavkov
• vrnjeni tip funkcije/metode in začetni zaviti oklepaj sta vedno na ločenih vrsticah:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// telo metode
	}

Začetni zaviti oklepaj na ločeni vrstici je pomemben za vizualno ločevanje signature funkcije/metode od telesa. Če je signatura na eni vrstici, je ločitev očitna (slika levo), če je na več vrsticah, se v PSR signature in telesa zlivajo (sredina), medtem ko sta v Nette standardu še naprej ločeni (desno):

Bloki dokumentacije (phpDoc)

Glavno pravilo: Nikoli ne podvajajte nobenih informacij v signaturi, kot je tip parametra ali vrnjeni tip, brez dodane vrednosti.

Dokumentacijski blok za definicijo razreda:

• Začne se z opisom razreda.
• Sledi prazna vrstica.
• Sledijo anotacije @property (ali @property-read, @property-write), ena za drugo. Sintaksa je: anotacija, presledek, tip, presledek, $ime.
• Sledijo anotacije @method, ena za drugo. Sintaksa je: anotacija, presledek, vrnjeni tip, presledek, ime(tip $param, …).
• Anotacija @author se izpušča. Avtorstvo se hrani v zgodovini izvorne kode.
• Lahko se uporabita anotaciji @internal ali @deprecated.

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

Dokumentacijski blok za lastnost, ki vsebuje samo anotacijo @var, bi moral biti enovrstičen:

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

Dokumentacijski blok za definicijo metode:

• Začne se s kratkim opisom metode.
• Brez prazne vrstice.
• Anotacije @param po posameznih vrsticah.
• Anotacija @return.
• Anotacije @throws, ena za drugo.
• Lahko se uporabita anotaciji @internal ali @deprecated.

Vsaki anotaciji sledi en presledek, z izjemo @param, za katero za boljšo berljivost sledita dva presledka.

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

Zavihki namesto presledkov

Zavihki imajo v primerjavi s presledki več prednosti:

• velikost zamika je mogoče prilagoditi v urejevalnikih in na spletu
• kodi ne vsiljujejo uporabnikove preference glede velikosti zamika, zato je koda bolje prenosljiva
• lahko jih napišemo z enim pritiskom tipke (kjerkoli, ne samo v urejevalnikih, ki spreminjajo zavihke v presledke)
• zamikanje je njihov namen
• spoštujejo potrebe slabovidnih in slepih kolegov

Z uporabo zavihkov v naših projektih omogočamo prilagajanje širine, kar se večini ljudi morda zdi nepotrebno, vendar je za ljudi z okvaro vida nujno.

Za slepe programerje, ki uporabljajo braillove zaslone, vsak presledek predstavlja eno braillovo celico. Če je torej privzeti zamik 4 presledki, zamik 3. stopnje zapravi 12 dragocenih braillovih celic, še preden se koda začne. Na 40-celičnem zaslonu, ki se najpogosteje uporablja pri prenosnikih, je to več kot četrtina razpoložljivih celic, ki so zapravljene brez kakršnekoli informacije.