> For the complete documentation index, see [llms.txt](https://mirkorap16.gitbook.io/clean-code/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mirkorap16.gitbook.io/clean-code/nomi-significativi.md).

# Nomi significativi

> There are only two hard things in Computer Science: cache invalidation and naming things.

I nomi sono dappertutto nel software (variabili, funzioni, argomenti, classi, istanze, file, cartelle...), per questo motivo è molto importante nominare bene le cose. Ecco delle semplici regole per scegliere dei buoni nomi.

## Usate nomi "parlanti"

I nomi devono essere parlanti. Già dal nome deve essere chiaro il perchè esiste, cosa fa e come viene utilizzato ciò che state nominando.

Esempio di cattivo nome:

```
$d = 12;
$list1 = [];
$a = true;
```

Esempio di buon nome:

```
$daysSinceCreation = 12;
$flaggedCells = [];
$isFlagged = true;
```

## Evitate la disinformazione

I nomi non devono essere ambigui e disinformativi. Se uso `$accountList` e non si tratta di una lista, ma di un gruppo di accounts, allora è meglio utilizzare `$accountGroup`.

## Adottate distinzioni sensate

Usare due nomi uguali che si distinguono solo per un valore posto alla fine del nome (Es. `$customer1` e `$customer2`) non è sensato. Piuttosto cercate di dare un nome che ben distingua le due cose (Es. `$buyer` e `$seller`). Anche nel nominare le classi si commette questo errore. Pensate a quante volte vi è capitato di trovare due classi che si chiamavano rispettivamente `Customer` e `CustomerData`. Qual è la differenza tra le due? Ecco perché è importante dare nomi sensati che ben distinguano le cose.

## Usate nomi pronunciabili

Evitate di dare nomi che siano difficili da pronunciare e di conseguenza da scrivere.

## Usate nomi ricercabili

I nomi devono essere anche facilmente ricercabili. Se usiamo nomi mono-lettera, quest'ultimi diventano impossibili da ricercare, poiché il risultato della ricerca darà migliaia di occorrenze. Evitate anche di usare magic numbers, meglio racchiuderli all'interno di costanti.

Valore difficile da ricercare:

```
if ($status === 1) {
  // ...
}
```

Valore facile da ricercare:

```
if ($status === Task::STATUS_CLOSED) {
  // ...
}
```

## Evitate le codifiche

I nomi codificati sono difficili da ricordare e capire, soprattutto per chi è stato neo-assunto.

## Suffissi

E' inutile aggiungere ai nomi di variabili, funzioni e interfacce dei suffissi. I moderni IDE, attraverso il Syntax Highlighting o tramite l'utilizzo di apposite icone, ci forniscono già delle informazioni che rendono inutile l'utilizzo di suffissi.

Nome di interfaccia da evitare:

```
interface ShapeFactoryInterface
```

Nome di interfaccia corretto:

```
interface ShapeFactory
```

## Nomi di classi

Il nome di una classe non dovrebbe essere un verbo. Inoltre evitate parole come `Manager`, `Processor`, `Data` o `Info` che spesso vengono utilizzate solo per distinguere i nomi e non aggiungono altre informazioni su ciò che fa la classe.

## Nomi di metodi

I nomi dei metodi dovrebbero contenere un verbo o una frase verbale, come `sendEmail`, `save`, `deleteCustomer`. Anche per i costruttori spesso è utile adottare un nome ([Named Constructor](http://blog.conorsmith.ie/named-constructors-in-php)) per rendere più chiaro quest'ultimo.

Costruttore poco chiaro:

```
$fulcrumPoint = new Complex(23.0);
```

Costruttore chiaro:

```
$fulcrumPoint = Complex::fromRealNumber(23.0);
```

## Una parola, un concetto

Scegliete una parola per un determinato concetto astratto e continuatela ad utilizzarla per tutto il codice. Per esempio, non ha senso utilizzare `fetch`, `retrieve` e `get` per metodi equivalenti di classi differenti. Se ad esempio abbiamo utilizzato `add` per la somma di due valori, non usiamo lo stesso nome per inserire un elemento all'interno di una lista. Piuttosto utilizzate qualche altro nome tipo `insert` o `append`.

## Usate nomi appartenenti al dominio

Cercate di utilizzare nomi appartenenti al dominio dell'applicazione.

## Aggiungere un contesto al nome

Aggiungendo un contesto al nome, quest'ultimo acquisisce maggiore chiarezza. Se prendo il nome `state`, vi risulta chiaro a cosa io mi stia riferendo? Se lo rinominassi in `addrState`, quest'ultimo diventerebbe subito più chiaro. Spesso anche creare una classe aiuta a dare contesto ai nomi (Es. la classe `Address` per rappresentare i campi di un indirizzo).

## Non aggiungete contesti superflui

Non bisogna abusare dei contesti nei nomi se non ce n'è di bisogno. Il nome `CustomerAddress` è un buon nome per rappresentare l'istanza di una classe, ma diventa un cattivo nome nel momento in cui lo utilizzo come nome per una classe, in quanto è superfluo aggiungere il contesto `Customer` per rappresentare dei semplici campi di un indirizzo.