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

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.