Come Scrivere Nomi Migliori per le Tue Variabili, Funzioni e Classi – Con Esempi

Il naming è una delle parti più importanti e sfidanti nella scrittura di codice pulito, manutenibile e scalabile. Un nome di variabile ben ponderato, ad esempio, può fungere da codice auto-documentante, risparmiando tempo ed sforzi nella comprensione della logica. Ma nomi scelti male, d’altra parte, possono portare a confusione e bug.

Questo articolo servirà come guida esaustiva su come trovare nomi significativi per nomi di classe, variabili e funzioni con esempi e migliori pratiche.

Perché è Importante il Naming?

• Leggibilità: I buoni nomi rendono il tuo codice intuitivo e riducono la curva di apprendimento per gli altri.

• Manutenibilità: È più facile rifattorizzare o fare debug di codice ben nominato.

• Collaborazione: Nomi chiari migliorano la comunicazione e la produttività del team.

• Scalabilità: I nomi significativi aiutano a mantenere gestibili i progetti di grandi dimensioni.

Stili Diversi di Convenzioni di Naming

Gli stili di convenzioni di naming diversi sono cruciali nel migliorare la leggibilità e la manutenibilità del codice attraverso vari linguaggi di programmazione.

Stili come camelCase, PascalCase, snake_case e kebab-case sono adattati a contesti e pratiche specifiche.

camelCase è ampiamente utilizzato per variabili e funzioni, mentre PascalCase è preferito per le classi. snake_case è un preferito in Python per la sua chiarezza, e kebab-case domina nel CSS per lo stile degli elementi HTML.

Ogni stile garantisce coerenza, rendendo il codice intuitivo per team e futuri sviluppatori. Ecco una tabella di riassunto rapido di alcune convenzioni di denominazione popolari insieme ai loro casi d’uso ed esempi:

Come Scegliere lo Stile Giusto

1. Specifico della Lingua: Seguire le convenzioni del linguaggio di programmazione o del framework. Ad esempio:

   • JavaScript: camelCase per variabili e funzioni, PascalCase per componenti.

   • Python: snake_case per variabili e funzioni.

   • CSS/HTML: kebab-case per nomi di classi e ID.

2. Standard del Team o del Progetto: La coerenza è fondamentale. Utilizzare lo stile concordato per il team/progetto.

3. Specifica dello Scopo: Utilizza stili di denominazione che rappresentino al meglio l’entità che viene denominata (ad esempio, costanti in SCREAMING_SNAKE_CASE).

Linee Guida Generali sulla Denominazione

Prima di entrare nei dettagli delle convenzioni di denominazione specifiche per i nomi di classe, variabili e funzioni, esploriamo alcuni principi universali:

1. Sii descrittivo e conciso: I nomi dovrebbero trasmettere lo scopo o il ruolo della variabile/funzione/ecc:

    // Male
    let x = 10;
   
    // Bene
    let maxUsersAllowed = 10;
   

2. Avoid abbreviazioni criptiche che potrebbero essere difficili da capire per altri sviluppatori (o anche per te stesso in futuro):

    // Male
    let usrNm = "John";
   
    // Bene
    let userName = "John";
   

3. Utilizza convenzioni di denominazione coerenti: Scegli uno stile di denominazione (camelCase, PascalCase, kebab-case, snake_case) e mantienilo per l’intero progetto.

4. Avoidare parole chiave riservate o nomi confusi:

    // Male
    let let = 5;
   
    // Bene
    let variableName = 5;
   

Ok, ora che abbiamo coperto le basi, approfondiamo alcune utili convenzioni di denominazione.

Come Creare Buoni Nomi di Classe

I nomi di classe definiscono il comportamento visuale o strutturale degli elementi nella tua applicazione. Scrivere nomi di classe chiari garantisce che il tuo HTML e CSS siano facili da capire e mantenere.

1. Utilizzare Nomi Descrittivi

I nomi di classe dovrebbero descrivere lo scopo dell’elemento, non il suo aspetto.

<!-- Male -->
<div class="red-button"></div>

<!-- Bene -->
<div class="primary-button"></div>

2. Seguire la Metodologia BEM (Block-Element-Modifier)

BEM è una convenzione popolare per scrivere CSS scalabile e manutenibile. Separa i componenti in:

• Blocco: Rappresenta il componente (ad esempio, card).

• Elemento: Rappresenta gli elementi figli del blocco (ad esempio, card__title).

• Modificatore: Rappresenta le variazioni del blocco o dell’elemento (ad esempio, card__title--highlighted).

Esempio:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. Usa il kebab-case

I nomi delle classi CSS sono tradizionalmente scritti in kebab-case per una migliore leggibilità.

<!-- Cattivo -->
<div class="primaryButton"></div>

<!-- Buono -->
<div class="primary-button"></div>

Come creare buoni nomi per le variabili

Le variabili contengono dati e dovrebbero avere nomi significativi che descrivono ciò che rappresentano.

1. Usa sostantivi per le variabili

Le variabili sono tipicamente sostantivi perché rappresentano entità o dati.

// Cattivo
let a = "John";

// Buono
let userName = "John";

2. Usa prefissi per aggiungere contesto

Aggiungere prefissi aiuta a chiarire il tipo o lo scopo di una variabile:

• Boolean: è, ha, può

• Numeri: massimo, minimo, totale

• Array: Utilizzare forme al plurale (ad esempio, utenti, elementi).

Esempio:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // MB
const usersList = ["John", "Jane"];

3. Evitare Nomi Generici

Evitare nomi come dati, valore, o elemento a meno che non siano necessari.

// Cattivo
let data = 42;

// Buono
let userAge = 42;

Come Creare Buoni Nomi di Funzioni

Le funzioni eseguono azioni, quindi i loro nomi dovrebbero riflettere l’operazione o il processo che eseguono.

1. Utilizzare Verbi per le Funzioni

Le funzioni sono orientate all’azione, quindi i loro nomi dovrebbero iniziare con un verbo:

// Cattivo
function userData() {
  // ...
}

// Buono
function fetchUserData() {
  // ...
}

2. Essere Specifici Riguardo alla Funzionalità

I nomi delle funzioni dovrebbero indicare cosa fanno.

// Cattivo
function handle() {
  // ...
}

// Buono
function handleFormSubmit() {
  // ...
}

3. Usa Prefissi per l’Intento

• Per i gestori di eventi: handle, on

• Per le utility: calculate, convert, format

• Per le operazioni di fetch: fetch, get, load

• Per i setter e getter: set, get

Esempio:

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

Come sapere se un Nome è Buono per una Variabile, Funzione o Classe

Per capire se un nome è buono per una variabile, funzione o classe, è importante valutarlo utilizzando diversi principi chiave. Ecco una guida per aiutarti a decidere se un nome è appropriato e significativo nel tuo contesto di programmazione:

1. Rappresenta lo Scopo?

I nomi orientati allo scopo sono la caratteristica più importante di una buona denominazione. Un nome dovrebbe immediatamente farti capire cosa rappresenta o fa la variabile, la funzione o la classe senza bisogno di leggere commenti o documentazione aggiuntiva.

Come valutare:

Chiediti: “Quando leggo questo nome, posso comprendere immediatamente il suo scopo?”

Esempio:

• userAge è migliore di a perché userAge ti dice cosa rappresenta la variabile, mentre a è troppo ambiguo.

2. È abbastanza specifico?

Il nome dovrebbe essere abbastanza specifico da riflettere il ruolo esatto dell’entità nel tuo codice. Nomi eccessivamente generici come data o temp possono essere confusi perché non forniscono un contesto sufficiente.

Come valutare:

Chiediti: “Questo nome è specifico rispetto a ciò che questa variabile, funzione o classe rappresenta nella mia applicazione?”

Esempio:

• calculateTaxAmount() è migliore di calculate() perché è chiaro cosa sta calcolando la funzione.

3. Segue una convenzione di denominazione coerente?

La coerenza nelle convenzioni di denominazione è fondamentale. Quando tutti i membri del team seguono le stesse convenzioni, il codice è più facile da comprendere e navigare.

Come valutare:

Chiedere: “Questo nome è coerente con le convenzioni di denominazione utilizzate nel resto del progetto?” Seguire le linee guida del progetto come:

• camelCase per variabili e funzioni (ad es., userAge)

• PascalCase per classi (ad es., UserProfile)

• UPPERCASE_SNAKE_CASE per costanti (ad es., MAX_USERS)

Esempio:

• Se il tuo team segue camelCase, userData è migliore di UserData.

4. Avoid Ambiguità?

Un buon nome elimina l’ambiguità. Non dovrebbe essere aperto a interpretazioni multiple. Se può significare cose diverse in contesti diversi, porterà a confusione.

Come valutare:

Chiedere: “Qualcuno non familiare con il codice potrebbe interpretare erroneamente a cosa si riferisce questo nome?”

Esempio:

• Invece di chiamare un booleano isValid, utilizzare isUserLoggedIn o isEmailVerified per rendere più chiaro ciò che viene controllato.

5. È Facile da Leggere e Pronunciare?

Sebbene non sia strettamente necessario, la facilità di lettura e pronuncia può migliorare la leggibilità e la manutenibilità complessiva del tuo codice.

Come valutare:

Chiedi: “Questo nome è facile da leggere ad alta voce e posso capirlo a colpo d’occhio?”

Evita nomi lunghi e usa abbreviazioni comuni solo quando sono ampiamente accettate.

Esempio:

• maxRetries è migliore di maximumNumberOfAttemptsToReconnect.

6. Evita la ridondanza?

Evita la ridondanza nei nomi. Non ripetere informazioni che sono già implicite o descritte dal contesto.

Come valutare:

Chiedi: “Sto ripetendo informazioni che sono già chiare dal contesto circostante?”

Esempio:

• Se hai una classe chiamata User, nominare un metodo userGetData() è ridondante. Invece, usa getData().

7. È auto-documentante?

I migliori nomi documentano se stessi. Nomi buoni riducono la necessità di commenti o spiegazioni aggiuntive.

Come valutare:

Chiedi: “Questo nome descrive completamente la variabile, la funzione o la classe senza richiedere un commento per spiegare cosa fa?”

Esempio:

• La funzione calculateTotalPrice è autoesplicativa, quindi non c’è bisogno di un commento aggiuntivo come “Questa funzione calcola il prezzo totale dopo lo sconto.”

8. È Contestuale e Pertinente al Dominio?

Il nome dovrebbe adattarsi al contesto del tuo progetto e al suo dominio. Ad esempio, le convenzioni di denominazione per un’applicazione web possono differire da quelle per un’applicazione mobile o un modello di machine learning.

Come Valutare:

Chiediti: “Questo nome è allineato con il dominio e il contesto del mio progetto?”

Se stai lavorando in un dominio specifico (ad esempio, finanza, salute, giochi), utilizza termini specifici del settore facilmente riconoscibili.

Esempio:

• In un’applicazione di gioco, healthPoints è più appropriato di hp, poiché riflette il suo significato.

9. È a Prova di Futuro?

Pensa a come il tuo codice evolverà. I nomi dovrebbero essere sufficientemente flessibili da poter accomodare futuri cambiamenti senza richiedere refactoring.

Come Valutare:

Chiediti: “Questo nome avrà ancora senso se la funzionalità cambia o il progetto cresce?”

Esempio:

• userInfo potrebbe diventare obsoleto se la struttura dei dati cambia. È meglio utilizzare userProfile se ti aspetti che vengano aggiunti più campi.

10. Evita Numeri Magici e Valori Codificati Duramente?

Numeri magici (numeri con significato non chiaro) dovrebbero essere evitati a favore di costanti nominate.

Come valutare:

Chiedi: “Questo nome rappresenta una costante significativa, o è solo un numero grezzo?”

Esempio:

• Piuttosto che utilizzare 1000, utilizza una costante come MAX_FILE_SIZE per spiegare il significato dietro al numero.

Esempi pratici

Esempio CSS

L’esempio CSS seguente dimostra come applicare le convenzioni di denominazione BEM (Block-Element-Modifier) per mantenere una gerarchia di classi strutturata e scalabile nel tuo foglio di stile:

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

Ecco cosa succede in questo codice:

• Denominazione BEM: navbar è il Blocco, che rappresenta il componente di navigazione principale.

• navbar__list è l’Elemento, un figlio del blocco, che rappresenta l’elenco degli elementi di navigazione.

• navbar__item è un altro Elemento che rappresenta singoli elementi dell’elenco.

• navbar__item--active è un Modificatore utilizzato per evidenziare la voce di menu attiva.
  Questo approccio rende semplice comprendere le relazioni e i ruoli all’interno di HTML e CSS, supportando stili modulari e riutilizzabili.

Esempio JavaScript

Questo esempio JavaScript mostra come utilizzare convenzioni di denominazione significative e coerenti per variabili e funzioni per rendere il codice autoesplicativo:

// Variabili
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// Funzioni
function fetchUserDetails(userId) {
  // Recupera i dati dell'utente dall'API
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

Ecco cosa succede nel codice:

• Variabili:

  • isUserLoggedIn: Una variabile booleana denominata in modo chiaro per indicarne lo scopo. Aggiungere il prefisso is aiuta a identificarla come booleana.

  • maxAllowedItems: Una costante con un prefisso di maiuscole max mostra che è un limite, rendendo chiaro il suo intento.

• Funzioni:

  • fetchUserDetails(userId): Il nome riflette lo scopo della funzione, ovvero recuperare i dettagli dell’utente. Il parametro userId è descrittivo e evita ambiguità.

  • calculateTotalPrice(cartItems): Il nome della funzione indica esplicitamente l’azione svolta. Il parametro cartItems è rilevante nel contesto del settore dell’e-commerce.

Perché è Buono: Queste convenzioni garantiscono che il codice sia leggibile e intuitivo, riducendo il carico cognitivo per altri sviluppatori che lavorano sullo stesso progetto.

Conclusione

Il dare nomi significativi è sia una convenzione importante che una forma d’arte che influisce significativamente sulla leggibilità e manutenibilità del tuo codice.

Cerca di seguire questi principi di base:

• Usa nomi descrittivi e concisi.

• Segui convenzioni coerenti come BEM per i nomi delle classi e camelCase per variabili e funzioni.

• Usa prefissi per aggiungere contesto e chiarezza.

Questi e gli altri suggerimenti che abbiamo discusso qui renderanno il tuo codice un piacere da utilizzare, che tu lo riveda mesi dopo o collabori con un team. Inizia ad applicare questi suggerimenti oggi e osserva la qualità del tuo codice decollare.