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. Cel mai simplu mod de a face acest lucru este să imitați codul existent.
Ideea este de a face ca tot codul să arate ca și cum ar fi fost scris de o singură persoană. .[perex]

Standardul de codare Nette corespunde [stilului de codare PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/], cu două excepții principale: folosește [tabulatoare în loc de spații |#tabs instead of spaces] pentru indentare și folosește [PascalCase pentru constantele de clasă |https://blog.nette.org/ro/pentru-mai-putine-tipete-in-cod].


Reguli generale .[#toc-general-rules]
=====================================

- Fiecare fișier PHP trebuie să conțină `declare(strict_types=1)`
- Două linii goale sunt folosite pentru a separa metodele pentru o mai bună lizibilitate.
- Motivul pentru utilizarea operatorului shut-up trebuie să fie documentat: `@mkdir($dir); // @ - directory may exist`
- În cazul în care se utilizează operatorul de comparație slab tipizat (de exemplu, `==`, `!=`, ...), intenția trebuie să fie documentată: `// == to accept null`
- Puteți scrie mai multe excepții într-un singur fișier `exceptions.php`
- Vizibilitatea metodelor nu este specificată pentru interfețe, deoarece acestea sunt întotdeauna publice.
- Fiecare proprietate, valoare de returnare și parametru trebuie să aibă un tip specificat. Pe de altă parte, pentru constantele finale, nu se specifică niciodată tipul, deoarece este evident.
- Ghilimelele simple trebuie utilizate pentru a delimita șirul de caractere, cu excepția cazului în care literalul conține el însuși apostrofuri.


Convenții de denumire .[#toc-naming-conventions]
================================================

- Evitați utilizarea abrevierilor, cu excepția cazului în care numele complet este excesiv.
- Folosiți majusculele pentru abrevierile din două litere și majusculele pascale/cămilă pentru abrevierile mai lungi.
- Utilizați un substantiv sau o expresie substantivală pentru numele clasei.
- Numele claselor trebuie să conțină nu numai specificitate (`Array`), ci și generalitate (`ArrayIterator`). Excepție fac atributele PHP.
- "Constantele de clasă și enumerațiile trebuie să utilizeze PascalCaps":https://blog.nette.org/ro/pentru-mai-putine-tipete-in-cod.
- "Interfețele și clasele abstracte nu trebuie să conțină prefixe sau postfixe":https://blog.nette.org/ro/prefixele-si-sufixele-nu-se-regasesc-in-numele-interfetelor precum `Abstract`, `Interface` sau `I`.


Înfășurare și paranteze .[#toc-wrapping-and-braces]
===================================================

Standardul de codificare Nette corespunde PSR-12 (sau stilului de codificare PER), dar în unele puncte îl specifică mai mult sau îl modifică:

- funcțiile săgeată se scriu fără spațiu înaintea parantezei, adică `fn($a) => $b`
- nu este necesară o linie goală între diferitele tipuri de instrucțiuni de import `use`
- tipul de retur al unei funcții/metode și paranteza curbă de deschidere se află întotdeauna pe linii separate:

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

Paranteza de deschidere pe o linie separată este importantă pentru separarea vizuală a semnăturii funcției/metodei de corp. Dacă semnătura se află pe o singură linie, separarea este clară (imaginea din stânga), dacă se află pe mai multe linii, în PSR semnăturile și corpurile se amestecă (în mijloc), în timp ce în standardul Nette acestea rămân separate (în dreapta):

[* new-line-after.webp *]


Blocuri de documentație (phpDoc) .[#toc-documentation-blocks-phpdoc]
====================================================================

Regula principală: nu duplicați niciodată informații din semnătură, cum ar fi tipul de parametru sau tipul de retur, fără nicio valoare adăugată.

Bloc de documentație pentru definirea clasei:

- Începe cu o descriere a clasei.
- Urmează o linie goală.
- Urmează, rând pe rând, adnotările `@property` (sau `@property-read`, `@property-write`). Sintaxa este: adnotare, spațiu, tip, spațiu, $nume.
- Urmează, rând pe rând, adnotările `@method`. Sintaxa este: annotation, space, return type, space, name(type $param, ...).
- Adnotarea `@author` este omisă. Autorul este păstrat într-un istoric al codului sursă.
- Se pot utiliza adnotările `@internal` sau `@deprecated`.

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

Blocul de documentație pentru proprietatea care conține doar adnotarea `@var` trebuie să fie pe o singură linie:

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

Blocul de documentație pentru definiția metodei:

- Începe cu o scurtă descriere a metodei.
- Nu există linii goale.
- Adnotările `@param`, rând pe rând.
- Adnotarea `@return`.
- Adnotările `@throws`, rând pe rând.
- Se pot utiliza adnotările `@internal` sau `@deprecated`.

Fiecare adnotare este urmată de un spațiu, cu excepția `@param`, care este urmată de două spații pentru o mai bună lizibilitate.

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


Tabulații în loc de spații .[#toc-tabs-instead-of-spaces]
=========================================================

Tabulațiile au mai multe avantaje față de spații:

- dimensiunea liniuței este personalizabilă în editori și "web":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size.
- nu impun dimensiunea de indentare preferată de utilizator asupra codului, astfel încât codul este mai portabil
- se pot tasta cu o singură apăsare de tastă (oriunde, nu doar în editorii care transformă filele în spații)
- scopul lor este indentarea
- respectați nevoile colegilor cu deficiențe de vedere și nevăzători

Prin utilizarea tabulațiilor în proiectele noastre, permitem personalizarea lățimii, ceea ce poate părea inutil pentru majoritatea oamenilor, dar este esențial pentru persoanele cu deficiențe de vedere.

Pentru programatorii nevăzători care folosesc afișaje braille, fiecare spațiu este reprezentat de o celulă braille și ocupă un spațiu prețios. Astfel, dacă indentarea implicită este de 4 spații, o indentare de nivelul 3 irosește 12 celule braille înainte de începerea codului.
Pe un afișaj cu 40 de celule, care este cel mai des utilizat pe laptopuri, înseamnă mai mult de un sfert din celulele disponibile irosite fără nicio informație.


{{priority: -1}}