Considerazioni sui nomi delle variabili

[f.faleschini]

Ciao.

Mi fa piacere condividere con voi una discussione che ho avuto ieri con i miei colleghi.

L’argomento era “cerchiamo di rendere il nostro codice più leggibile scegliendo dei nomi sensati per gli identificativi”.

Chiaramente l’argomento ha mille declinazioni, ma noi abbiamo approfondito un caso particolare: quello in cui una variabile cambia significato “nel corso di un metodo”.

Per evitare troppi commenti nel codice o trarre in inganno chi legge il codice un trucco che mi sono inventato (e che deriva dal buonsenso) è quello di introdurre ad un certo punto in un metodo una nuova variabile con un nome sensato e da lì in poi usare quella e non la prima.

Mi spiego con un esempio.

Ecco il caso (puramente didattico) che ho creato:

l problema sta nella allActiveUsers, che a metà codice in realtà diventa, in pratica, allExperiencedUsers perché ho tolto dalla collection gli utenti senza abbastanza esperienza. Quindi chi legge il codice di corsa e si sofferma su:

potrebbe pensre che questo metodo ricompensi tutti gli utenti, a prescindere dalla loro esperienza.

Certo, si può mettere un commento, ma non è elegante:

Una soluzione non otttimale è quella di dare precedenza allo stato “finale” della collection e scegliere di nominare la collection in base a cosa contiene alla fine:

Ma siamo daccapo e chi legge questa parte si chiederà come mai sto eliminando degli utenti esperti dalla collection degli utenti esperti:

La soluzione che propongo è creare una nuova variabile da usare da metà metodo in poi:

Cosa ne pensate?

Avete altre tecniche di naming che vi piace condividere?

Io sono stato molto inspirato da Clean Code di Robert C. Martin, che tra l’altro si trova anche in pdf in italiano cercandolo su google.

Buona giornata!

[r.bianco]

Concordo.
In generale, se la variabile è usata per qualcosa di inequivocabile o che non ha impatto sull’algoritmo, uso un nome generico (Index, …), così posso riutilizzarla. Se la variabile assume un significato specifico all’interno dell’algoritmo, uso un nome che ne indica il contenuto e la uso solo e soltanto per quello. Altrimenti il codice diventa illeggibile.
Altra cosa a cui mi sono abituato è mantenere la prima lettera suggerita da InDe F. in base al tipo, ed aggiungere successivamente il nome da me scelto (iNrPezzi, sNomeUtente, …). Questo mi torna utile sia per una maggiore leggibilità del codice, sia in un’eventuale verifica che inde abbia rispettato i tipi da me indicati e non li abbia cambiati per una errata assegnazione.

[f.faleschini]

Grazie.

A me non piace tenere la lettera che Inde mette, però tengo spesso (a volte li cambio ma sono “tollerante”) i nomi che crea la select into variables, ad esempio vCount, che sarebbe più bello chiamare ad esempio errorsCount, però in un certo senso mi sono affezionato a quel “v”.

Ciao.

[stefano.masiero]

Ciao Francesco
sicuramente approvo l’opzione di creare una nuova collection ma:

• non toglierei gli elementi da allActiveUsers: se in seguito volessi ancora usare questa collection avrei tutti gli utenti o solo quelli inesperti in funzione del fatto che abbia girato o meno il filtro su quelli esperti.
• aggiungerei gli utenti esperti in allExperiencedUsers nel primo ciclo con addRef: in un unico ciclo verifico se l’utente è esperto, gli do la ricompensa, lo traccio nella sua collection dedicata.

In sintesi avrei solo questa logica:

for each User u in allActiveUsers
{
  if (u.hasEnoughExperience()) {
    u.reward()
    allExperiencedUsers.addRef(u);
  }
  else {
    allUnexperiendeUsers.addRef(u); // potrebbe capitare di dover far qualcosa anche su di loro
  }
}

In generale evito di riusare variabili nella stessa funzione per scopi diversi. Se mi trovo nella situazione significa che potrei spezzare la funzione in due funzioni oppure c’è qualcosa che non sto modellando a dovere, quindi faccio un po’ di tentativi di refactoring finchè non risolvo la situazione.

Grazie per gli argomenti sempre interessanti!
Stefano

[giorba]

Concordo con la tecnica illustrata, utilizzare nomi di variabili ed oggetti che facciano capire subito cosa contengano, senza doversi leggere il codice, è assolutamente utile sotto più punti di vista. Permettono di capire meglio il codice e anche di comprendere meglio la volontà del programmatore, il che può tornare utile anche per risolvere eventuali problemi.
Anche se questo post è chiaramente dedicato a Foundation, voglio condividere la mia personale naming convention che uso per Javascript (quindi IDC) ed i linguaggi typeless in generale, seguita in tutto il codice che produciamo in azienda.
Ogni nome di variabile lo faccio seguire da una serie di indicatori che permettono di capire il tipo di contenuto, se la variabile è utilizzata come parametro di funzione/metodo o se ha uno scope globale, secondo questo schema:

[g]|[p]|[a]<int|flt|str|bln|cur|dte|obj|...>NomeDellaVariabile

dove:

• g indica se la variabile ha uno scope globale
• p se è un parametro di una funzione o metodo
• a se è un array
• int, flt, str, bln, cur, dte, obj se contiene un intero, float, stringa, booleano, currency, date, oggetto e così via

I nomi delle variabili sono in camel case “vero”, con la prima lettera maiuscola.
Le costanti sono scritte tutte in maiuscolo, con eventuali spazi sostituiti dagli underscore.
Per esempio:

• intNumero, è una variabile numerica di tipo intero:
• pintNumero, un parametro di funzione di tipo intero:
• gobjOggetto, un oggetto generico globale
• astrEmails, un array di stringhe che contiene degli indirizzi email
• DEBUG_ATTIVO, è una costante

E così via. Anche se Javascript è typeless, trovo che ragionare come se fosse a tipizzazione forte può essere un vantaggio nella progettazione del codice e per la sua leggibilità.

[gabriele.lesignoli]

@stefano.masiero

sicuramente approvo l’opzione di creare una nuova collection ma:

• non toglierei gli elementi da allActiveUsers: se in seguito volessi ancora usare questa collection avrei tutti gli utenti o solo quelli inesperti in funzione del fatto che abbia girato o meno il filtro su quelli esperti.
• aggiungerei gli utenti esperti in allExperiencedUsers nel primo ciclo con addRef: in un unico ciclo verifico se l’utente è esperto, gli do la ricompensa, lo traccio nella sua collection dedicata.

Quoto @stefano.masiero , mi trovo molto meglio creando due collection/array/gruppi con le loro caratteristiche (eventualmente ricaricandoli nel caso la schermata) :

• Nel caso mi serva la collection con tutti gli utenti la trovo ancora ,

• Nel caso mi serva solo una con utenti specifici la posso calcolare o richiamare se l’ho già generata (come nel tuo caso con allExperiencedUsers)

• In generale trovo il codice più al riparo da errori in in questo modo, nel caso debba fare dei cambiamenti dopo mesi e non mi ricordi immediatamente perchè ho fatto così (con la mia memoria da pesce rosso…)

Concordo con una sintassi standard per i nomi delle variabili, aiuta anche in fase di debug a capire immediatamente cosa e dove è sbagliato : noi usiamo un prefisso prima del nome della variabile, tipo a per indicare array, b per booleani e via dicendo in modo simile a @giorba , ovviamente ognuno ha il suo metodo e ogni metodo è valido!

Saluti, Gabriele