# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mirkorap16.gitbook.io/clean-code/nomi-significativi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.