Standard de codificare

Acest document descrie regulile și recomandările pentru dezvoltarea Nette. Atunci când contribuiți cu cod la Nette, trebuie să le respectați. Cea mai simplă modalitate de a face acest lucru este să imitați codul existent. Ideea este ca tot codul să arate ca și cum ar fi fost scris de o singură persoană.

Standardul de codificare Nette corespunde PSR-12 Extended Coding Style cu două excepții principale: pentru indentare folosește tabulátory místo mezer în loc de spații și pentru constantele de clasă folosește PascalCase.

Reguli generale

• Fiecare fișier PHP trebuie să conțină declare(strict_types=1)
• Două rânduri goale sunt folosite pentru a separa metodele pentru o mai bună lizibilitate.
• Motivul utilizării operatorului shut-up trebuie documentat: @mkdir($dir); // @ - directorul poate exista.
• Dacă este utilizat un operator de comparație slab tipizat (adică ==, !=, …), intenția trebuie documentată: // == acceptă null
• Într-un singur fișier exceptions.php puteți scrie mai multe excepții.
• Pentru interfețe nu se specifică vizibilitatea metodelor, deoarece sunt întotdeauna publice.
• Fiecare proprietate, valoare returnată și parametru trebuie să aibă tipul specificat. În schimb, la constantele finale nu specificăm niciodată tipul, deoarece este evident.
• Pentru delimitarea șirurilor de caractere ar trebui folosite ghilimele simple, cu excepția cazurilor în care literalul însuși conține apostrofuri.

Convenții de denumire

• Nu utilizați abrevieri, cu excepția cazului în care numele complet este prea lung.
• Pentru abrevierile de două litere utilizați majuscule, pentru abrevierile mai lungi pascal/camel case.
• Pentru numele clasei utilizați un substantiv sau o sintagmă.
• Numele claselor trebuie să conțină nu numai specificitatea (Array), ci și generalitatea (ArrayIterator). Excepție fac atributele limbajului PHP.
• Constantele de clasă și enum-urile ar trebui să utilizeze PascalCaps.
• Interfețele și clasele abstracte nu ar trebui să conțină prefixe sau sufixe precum Abstract, Interface sau I.

Wrapping and Braces

Standardul de codificare Nette corespunde PSR-12 (respectiv PER Coding Style), în unele puncte îl completează sau îl modifică:

• funcțiile arrow se scriu fără spațiu înainte de paranteză, adică fn($a) => $b
• nu se cere un rând gol între diferite tipuri de use import statements
• tipul returnat al funcției/metodei și acolada de deschidere sunt întotdeauna pe rânduri separate:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// corpul metodei
	}

Acolada de deschidere pe un rând separat este importantă pentru separarea vizuală a semnăturii funcției/metodei de corp. Dacă semnătura este pe un singur rând, separarea este clară (imaginea din stânga), dacă este pe mai multe rânduri, în PSR semnăturile și corpurile se contopesc (mijloc), în timp ce în standardul Nette sunt în continuare separate (dreapta):

Blocuri de documentație (phpDoc)

Regula principală: Nu duplicați niciodată informații în semnătură, cum ar fi tipul parametrului sau tipul returnat, fără valoare adăugată.

Blocul de documentație pentru definirea clasei:

• Începe cu descrierea clasei.
• Urmează un rând gol.
• Urmează adnotările @property (sau @property-read, @property-write), una după alta. Sintaxa este: adnotare, spațiu, tip, spațiu, $nume.
• Urmează adnotările @method, una după alta. Sintaxa este: adnotare, spațiu, tip returnat, spațiu, nume(tip $param, …).
• Adnotarea @author se omite. Autoritatea este păstrată în istoricul codului sursă.
• Se pot utiliza adnotările @internal sau @deprecated.

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

Blocul de documentație pentru o proprietate, care conține doar adnotarea @var, ar trebui să fie pe un singur rând:

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

Blocul de documentație pentru definirea metodei:

• Începe cu o scurtă descriere a metodei.
• Niciun rând gol.
• Adnotările @param pe rânduri separate.
• Adnotarea @return.
• Adnotările @throws, una după alta.
• Se pot utiliza adnotările @internal sau @deprecated.

După fiecare adnotare urmează un singur spațiu, cu excepția @param, după care, pentru o mai bună lizibilitate, urmează două spații.

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

Tabulatori în loc de spații

Tabulatorii au mai multe avantaje față de spații:

• dimensiunea indentării poate fi personalizată în editoare și pe web
• nu impun codului preferința utilizatorului privind dimensiunea indentării, astfel încât codul este mai portabil
• pot fi scrise cu o singură apăsare de tastă (oriunde, nu doar în editoarele care transformă tabulatorii în spații)
• indentarea este scopul lor
• respectă nevoile colegilor cu deficiențe de vedere și nevăzători

Utilizând tabulatori în proiectele noastre, permitem personalizarea lățimii, ceea ce poate părea o inutilitate pentru majoritatea oamenilor, dar este esențială pentru persoanele cu deficiențe de vedere.

Pentru programatorii nevăzători care utilizează afișaje Braille, fiecare spațiu reprezintă o celulă Braille. Deci, dacă indentarea implicită este de 4 spații, indentarea de nivel 3 irosește 12 celule Braille valoroase chiar înainte de începutul codului. Pe un afișaj de 40 de celule, care este cel mai frecvent utilizat la laptopuri, aceasta reprezintă mai mult de un sfert din celulele disponibile, care sunt irosite fără nicio informație.