Standard di codifica
********************

.[perex]
Questo documento descrive le regole e le raccomandazioni per lo sviluppo di Nette. Quando contribuite con codice a Nette, dovete seguirle. Il modo più semplice per farlo è imitare il codice esistente. L'obiettivo è che tutto il codice sembri scritto da una sola persona.

Lo Standard di Codifica Nette corrisponde a [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] con due eccezioni principali: utilizza [#tabulazioni invece di spazi] per l'indentazione e [PascalCase per le costanti di classe|https://blog.nette.org/it/for-less-screaming-in-the-code].


Regole generali
===============

- Ogni file PHP deve contenere `declare(strict_types=1)`
- Due righe vuote vengono utilizzate per separare i metodi per una migliore leggibilità.
- Il motivo dell'uso dell'operatore shut-up deve essere documentato: `@mkdir($dir); // @ - la directory potrebbe esistere`.
- Se viene utilizzato un operatore di confronto debolmente tipizzato (cioè `==`, `!=`, ...), l'intenzione deve essere documentata: `// == accetta null`
- In un unico file `exceptions.php` è possibile scrivere più eccezioni.
- Per le interfacce non viene specificata la visibilità dei metodi, poiché sono sempre pubblici.
- Ogni proprietà, valore di ritorno e parametro deve avere un tipo specificato. Al contrario, per le costanti finali non specifichiamo mai il tipo, poiché è ovvio.
- Per delimitare una stringa dovrebbero essere usate le virgolette singole, ad eccezione dei casi in cui il letterale stesso contiene apostrofi.


Convenzioni di denominazione
============================

- Non utilizzate abbreviazioni, a meno che il nome completo non sia troppo lungo.
- Per le abbreviazioni di due lettere utilizzate lettere maiuscole, per le abbreviazioni più lunghe pascal/camel case.
- Per il nome di una classe utilizzate un sostantivo o una frase nominale.
- I nomi delle classi devono contenere non solo la specificità (`Array`), ma anche la generalità (`ArrayIterator`). Fanno eccezione gli attributi del linguaggio PHP.
- "Le costanti di classe e gli enum dovrebbero usare PascalCaps":https://blog.nette.org/it/for-less-screaming-in-the-code.
- "Le interfacce e le classi astratte non dovrebbero contenere prefissi o suffissi":https://blog.nette.org/it/prefixes-and-suffixes-do-not-belong-in-interface-names come `Abstract`, `Interface` o `I`.


A capo e parentesi graffe
=========================

Lo Standard di Codifica Nette corrisponde a PSR-12 (risp. PER Coding Style), in alcuni punti lo completa o lo modifica:

- le arrow function si scrivono senza spazio prima della parentesi, cioè `fn($a) => $b`
- non è richiesta una riga vuota tra diversi tipi di `use` import statements
- il tipo di ritorno della funzione/metodo e la parentesi graffa di apertura sono sempre su righe separate:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// corpo del metodo
	}
```

La parentesi graffa di apertura su una riga separata è importante per la separazione visiva della firma della funzione/metodo dal corpo. Se la firma è su una riga, la separazione è chiara (immagine a sinistra), se è su più righe, in PSR la firma e il corpo si fondono (al centro), mentre nello standard Nette rimangono separati (a destra):

[* new-line-after.webp *]


Blocchi di documentazione (phpDoc)
==================================

Regola principale: Non duplicare mai alcuna informazione nella firma, come il tipo di parametro o il tipo di ritorno, senza un valore aggiunto.

Blocco di documentazione per la definizione di una classe:

- Inizia con la descrizione della classe.
- Segue una riga vuota.
- Seguono le annotazioni `@property` (o `@property-read`, `@property-write`), una dopo l'altra. La sintassi è: annotazione, spazio, tipo, spazio, $nome.
- Seguono le annotazioni `@method`, una dopo l'altra. La sintassi è: annotazione, spazio, tipo di ritorno, spazio, nome(tipo $param, ...).
- L'annotazione `@author` viene omessa. L'autorialità viene conservata nella cronologia del codice sorgente.
- Possono essere utilizzate le annotazioni `@internal` o `@deprecated`.

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

Un blocco di documentazione per una proprietà, che contiene solo l'annotazione `@var`, dovrebbe essere su una sola riga:

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

Blocco di documentazione per la definizione di un metodo:

- Inizia con una breve descrizione del metodo.
- Nessuna riga vuota.
- Annotazioni `@param` su righe separate.
- Annotazione `@return`.
- Annotazioni `@throws`, una dopo l'altra.
- Possono essere utilizzate le annotazioni `@internal` o `@deprecated`.

Dopo ogni annotazione segue uno spazio, ad eccezione di `@param`, dopo la quale seguono due spazi per una migliore leggibilità.

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


Tabulazioni invece di spazi
===========================

Le tabulazioni hanno diversi vantaggi rispetto agli spazi:

- la dimensione dell'indentazione può essere personalizzata negli editor e sul "web":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- non impongono al codice la preferenza dell'utente sulla dimensione dell'indentazione, quindi il codice è più portabile
- possono essere scritte con un solo tasto (ovunque, non solo negli editor che trasformano le tabulazioni in spazi)
- l'indentazione è il loro scopo
- rispettano le esigenze dei colleghi ipovedenti e non vedenti

Utilizzando le tabulazioni nei nostri progetti, consentiamo la personalizzazione della larghezza, che può sembrare superflua alla maggior parte delle persone, ma è essenziale per le persone con disabilità visive.

Per i programmatori non vedenti che utilizzano display Braille, ogni spazio rappresenta una cella Braille. Quindi, se l'indentazione predefinita è di 4 spazi, l'indentazione di 3° livello spreca 12 preziose celle Braille prima ancora che inizi il codice. Su un display a 40 celle, che è il più comune per i notebook, questo rappresenta più di un quarto delle celle disponibili sprecate senza alcuna informazione.


{{priority: -1}}