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.

Lo standard di codifica di Nette corrisponde allo stile di codifica esteso PSR-12, con due eccezioni principali: utilizza le tabulazioni invece degli spazi per l'indentazione e usa PascalCase per le costanti di classe.

Regole generali

• 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

• 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.
• Le interfacce e le classi astratte non devono contenere prefissi o postfissi come Abstract, Interface o I.

Avvolgimenti e parentesi graffe

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:

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

Blocchi di documentazione (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.

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

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

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

Le tabulazioni presentano diversi vantaggi rispetto agli spazi:

• la dimensione dell'indentazione è personalizzabile negli editor e nel web:https://developer.mozilla.org/…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.