Standard kodiranja

V tem dokumentu so opisana pravila in priporočila za razvoj Nette. Ko prispevate kodo za Nette, jih morate upoštevati. To najlažje storite tako, da posnemate obstoječo kodo. Ideja je, da je vsa koda videti, kot da jo je napisala ena oseba.

Kodirni standard Nette ustreza razširjenemu kodirnemu slogu PSR-12 z dvema glavnima izjemama: za alineje uporablja tabulatorje namesto presledkov in za konstante razredov uporablja PascalCase.

Splošna pravila

• Vsaka datoteka PHP mora vsebovati declare(strict_types=1)
• Dve prazni vrstici se uporabljata za ločevanje metod zaradi boljše berljivosti.
• Razlog za uporabo operatorja shut-up mora biti dokumentiran: @mkdir($dir); // @ - directory may exist
• Če se uporablja šibko tipiziran primerjalni operator (tj. ==, !=, …), je treba namen dokumentirati: // == to accept null
• V eno datoteko lahko zapišete več izjem exceptions.php
• Vidnost metod za vmesnike ni določena, ker so vedno javne.
• Vsaka lastnost, povratna vrednost in parameter morajo imeti določen tip. Po drugi strani pa za končne konstante nikoli ne določimo tipa, ker je to očitno.
• Za razmejitev niza je treba uporabiti enojne narekovaje, razen kadar sam literal vsebuje apostrofe.

Konvencije za poimenovanje

• Izogibajte se uporabi kratic, razen če je polno ime pretirano.
• Za dvočrkovne kratice uporabljajte velike črke, za daljše kratice pa pascal/camel črke.
• Za ime razreda uporabite samostalnik ali samostalniško besedno zvezo.
• Imena razredov morajo poleg specifičnosti (Array) vsebovati tudi splošnost (ArrayIterator). Izjema so atributi PHP.
• Konstante razredov in enumi morajo uporabljati PascalCaps
• Vmesniki in abstraktni razredi ne smejo vsebovati predpon ali postfiksov kot so Abstract, Interface ali I.

Ovijanje in oglati oklepaji

Nette Coding Standard ustreza PSR-12 (ali PER Coding Style), v nekaterih točkah pa ga podrobneje opredeljuje ali spreminja:

• puščice so zapisane brez presledka pred oklepajem, tj. fn($a) => $b
• med različnimi vrstami stavkov za uvoz use ni potrebna prazna vrstica
• tip vrnitve funkcije/metode in začetni oglati oklepaj sta vedno v ločenih vrsticah:

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

Začetni oglati oklepaj v ločeni vrstici je pomemben za vizualno ločitev podpisa funkcije/metode od telesa. Če je podpis v eni vrstici, je ločitev jasna (slika na levi), če je v več vrsticah, se v PSR podpisi in telesa zlijejo (na sredini), medtem ko v standardu Nette ostanejo ločeni (na desni):

Bloki dokumentacije (phpDoc)

Glavno pravilo: nikoli ne podvajajte informacij o podpisu, kot sta vrsta parametra ali vrsta vrnitve, brez dodane vrednosti.

Dokumentacijski blok za definicijo razreda:

• Začne se z opisom razreda.
• Sledi prazna vrstica.
• Sledijo opombe @property (ali @property-read, @property-write), ena za drugo. Sintaksa je: anotacija, presledek, tip, presledek, $name.
• Sledijo @method anotacije, ena za drugo. Sintaksa je: annotation, space, return type, space, name(type $param, …).
• Anotacija @author je izpuščena. Avtorstvo se hrani v zgodovini izvorne kode.
• Uporabita se lahko opombi @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 opombo @var, mora biti v eni vrstici:

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

Dokumentacijski blok za definicijo metode:

• Začne se s kratkim opisom metode.
• Brez prazne vrstice.
• Anotacije @param, ena za drugo.
• Opomba @return.
• Anotacije @throws, ena za drugo.
• Uporabijo se lahko anotacije @internal ali @deprecated.

Vsaki anotaciji sledi en presledek, razen @param, ki ji zaradi boljše berljivosti sledita dva presledka.

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

Tabelatorji namesto presledkov

Zavihki imajo več prednosti pred presledki:

• velikost alineje je mogoče prilagoditi v urejevalnikih in spletu
• v kodo ne vsiljujejo uporabnikovih preferenc glede velikosti alineje, zato je koda bolj prenosljiva
• lahko jih vnesete z enim pritiskom tipke (kjer koli, ne le v urejevalnikih, ki zavihke spremenijo v presledke)
• njihov namen je izrezovanje
• spoštujte potrebe slabovidnih in slepih sodelavcev

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

Za slepe programerje, ki uporabljajo brajeve zaslone, je vsak presledek predstavljen z brajevo celico in zavzema dragocen prostor. Če je privzeta alineja 4 presledki, se pri alineji tretje stopnje pred začetkom kode porabi 12 celic brajeve pisave. Na 40-celičnem zaslonu, ki se najpogosteje uporablja na prenosnih računalnikih, je to več kot četrtina razpoložljivih celic, ki so zapravljene brez kakršne koli informacije.