Standard di codifica

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 con due eccezioni principali: utilizza tabulazioni invece di spazi per l'indentazione e PascalCase per le costanti di classe.

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.
• Le interfacce e le classi astratte non dovrebbero contenere prefissi o suffissi 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:

	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):

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.

/**
 * 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:

/** @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à.

/**
 * 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
• 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.