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

Questo documento descrive le regole e le raccomandazioni per lo sviluppo di Nette. Quando si contribuisce al codice di Nette, è necessario seguirle. Il modo più semplice per farlo è imitare il codice esistente.
L'idea è quella di far sembrare che tutto il codice sia stato scritto da una sola persona. .[perex]

Lo standard di codifica di Nette corrisponde allo [stile di codifica esteso PSR-12 |https://www.php-fig.org/psr/psr-12/], con due eccezioni principali: utilizza le [tabulazioni invece degli spazi |#tabs instead of spaces] per l'indentazione e usa [PascalCase per le costanti di classe |https://blog.nette.org/it/per-non-urlare-nel-codice].


Regole generali .[#toc-general-rules]
=====================================

- Ogni file PHP deve contenere `declare(strict_types=1)`
- Due righe vuote sono usate per separare i metodi per una migliore leggibilità.
- La ragione dell'uso dell'operatore shut-up deve essere documentata: `@mkdir($dir); // @ - directory may exist`
- Se viene utilizzato un operatore di confronto a tipizzazione debole (ad esempio `==`, `!=`, ...), l'intenzione deve essere documentata: `// == to accept null`
- È possibile scrivere più eccezioni in un file `exceptions.php`
- La visibilità dei metodi non è specificata per le interfacce, perché sono sempre pubblici.
- Ogni proprietà, valore di ritorno e parametro deve avere un tipo specificato. Per le costanti finali, invece, non si specifica mai il tipo perché è ovvio.
- Gli apici singoli devono essere usati per delimitare la stringa, tranne quando il letterale stesso contiene apostrofi.


Convenzioni di denominazione .[#toc-naming-conventions]
=======================================================

- Evitare l'uso di abbreviazioni, a meno che il nome completo non sia eccessivo.
- Usare il maiuscolo per le abbreviazioni di due lettere e il pascal/camel case per le abbreviazioni più lunghe.
- Usare un sostantivo o una frase sostantiva per il nome della classe.
- I nomi delle classi devono contenere non solo la specificità (`Array`) ma anche la generalità (`ArrayIterator`). Fanno eccezione gli attributi PHP.
- "Le costanti di classe e gli enum dovrebbero usare il PascalCaps":https://blog.nette.org/it/per-non-urlare-nel-codice.
- "Le interfacce e le classi astratte non devono contenere prefissi o postfissi":https://blog.nette.org/it/i-prefissi-e-i-suffissi-non-appartengono-ai-nomi-delle-interfacce come `Abstract`, `Interface` o `I`.


Avvolgimenti e parentesi graffe .[#toc-wrapping-and-braces]
===========================================================

Lo standard di codifica Nette corrisponde al PSR-12 (o stile di codifica PER), in alcuni punti lo specifica maggiormente o lo modifica:

- le funzioni freccia sono scritte senza uno spazio prima delle parentesi, cioè `fn($a) => $b`
- non è richiesta una riga vuota tra i diversi tipi di dichiarazioni di importazione `use`
- il tipo di ritorno di una 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 separare visivamente la firma della funzione/metodo dal corpo. Se la firma è su una riga, la separazione è netta (immagine a sinistra), mentre se è su più righe, nel PSR le firme e i corpi si fondono insieme (al centro), mentre nello standard Nette rimangono separati (a destra):

[* new-line-after.webp *]


Blocchi di documentazione (phpDoc) .[#toc-documentation-blocks-phpdoc]
======================================================================

La regola principale: non duplicare mai le informazioni della firma, come il tipo di parametro o il tipo di ritorno, senza alcun valore aggiunto.

Blocco di documentazione per la definizione della classe:

- Inizia con una descrizione della classe.
- Segue una riga vuota.
- Seguono le annotazioni `@property` (o `@property-read`, `@property-write`), una per riga. La sintassi è: annotazione, spazio, tipo, spazio, $nome.
- Seguono le annotazioni di `@method`, una per riga. La sintassi è: annotazione, spazio, tipo di ritorno, spazio, nome(tipo $param, ...).
- L'annotazione `@author` è omessa. La paternità è conservata nella cronologia del codice sorgente.
- È possibile utilizzare le annotazioni `@internal` o `@deprecated`.

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

Il blocco di documentazione per la proprietà che contiene solo l'annotazione `@var` deve essere a riga singola:

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

Blocco di documentazione per la definizione del metodo:

- Inizia con una breve descrizione del metodo.
- Nessuna riga vuota.
- Le annotazioni di `@param`, una per riga.
- L'annotazione `@return`.
- Le annotazioni di `@throws`, una per riga.
- È possibile utilizzare le annotazioni `@internal` o `@deprecated`.

Ogni annotazione è seguita da uno spazio, tranne quella di `@param` che è seguita da due spazi per una migliore leggibilità.

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


Tabulazioni al posto degli spazi .[#toc-tabs-instead-of-spaces]
===============================================================

Le tabulazioni presentano diversi vantaggi rispetto agli spazi:

- la dimensione dell'indentazione è personalizzabile negli editor e nel  web:https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- non impongono al codice le preferenze di indentazione dell'utente, quindi il codice è più portabile
- si possono digitare con un solo tasto (ovunque, non solo negli editor che trasformano le tabulazioni in spazi)
- l'indentazione è il loro scopo
- rispettare le esigenze dei colleghi ipovedenti e non vedenti

Utilizzando le tabulazioni nei nostri progetti, consentiamo la personalizzazione della larghezza, che può sembrare superflua per la maggior parte delle persone, ma che è essenziale per le persone con problemi di vista.

Per i programmatori non vedenti che utilizzano display braille, ogni spazio è rappresentato da una cella braille e occupa spazio prezioso. Quindi, se l'indentazione predefinita è di 4 spazi, un'indentazione di terzo livello spreca 12 celle braille prima dell'inizio del codice.
Su un display a 40 celle, che è quello più comunemente usato sui computer portatili, si tratta di più di un quarto delle celle disponibili sprecate senza alcuna informazione.


{{priority: -1}}