10 consigli pratici per scrivere codice comprensibile... agli umani
Il codice non deve parlare solo alle macchine ma anche alle persone: eccome come.
Martin Fowler, software engineer, sviluppatore, autore di numerosi libri e tra i massimi esperti di programmazione, ha scritto:
“È facile scrivere codice che un computer può eseguire. Difficile è scrivere codice che un uomo può capire”. (1)
In effetti, quando si parla di linguaggi di programmazione, a volte si dimentica che per noi umani sono come una lingua straniera (anche se per nerd e geek non è sempre così!). Siamo tutti più o meno in grado di studiarla e parlarla ma non tutti riusciamo a farci capire, specialmente se non ci limitiamo a un semplice saluto o a un “come ti chiami?”, ma interagiamo in modo culturalmente rilevante.
Prendendo spunto da questa citazione vogliamo parlarti di un aspetto tra i più trascurati dai programmatori: la leggibilità e comprensibilità del codice sorgente tra gli umani.
Già, perché proprio come Fowler, crediamo che per realizzare un buon software non basti che un codice funzioni senza bug (ma ne esistono?) e sia veloce, ma che debba anche essere facilmente leggibile e comprensibile – e quindi modificabile e manutenibile – anche dopo molto tempo dal programmatore che lo ha creato.
Per capirci: caro sviluppatore, non ti è mai capitato di leggere un pezzo di codice e dire “ma chi l’ha sviluppata ’sta c…?” prima di capire di averlo fatto tu?
Lo stesso vale per altri programmatori del medesimo gruppo di lavoro, quando lo sviluppo riguarda più persone impegnate in grandi progetti che, nella maggior parte dei casi, non si conoscono, e quindi non possono che rifarsi al codice stesso e alla sua documentazione.
Scrivere codice in modo chiaro, così che possa essere letto e compreso da più persone, è dunque davvero molto importante e sicuramente più di quanto si pensi.
Un approccio che tra l’altro strizza l’occhio al nostro concetto di armonia: per noi di ESSE I un codice armonioso è scritto anche per gli altri, non solo per noi stessi e la macchina, in modo da favorire una collaborazione serena tra i membri del team.
Per certi versi un gesto di empatia umana condivisa.
Vogliamo allora lasciarti i nostri “10 consigli pratici per scrivere codice comprensibile agli umani” e, al termine, un’ulteriore riflessione su questo importante argomento.
Pensiamo che se sei un programmatore alle prime armi o un appassionato, a differenza di chi è già esperto, potresti trovarli molto utili.
1) Usa nomi significativi e chiari
Il nostro primo consiglio è di utilizzare nomi significativi per variabili, funzioni e classi.
I nomi dovrebbero riflettere chiaramente la loro funzione e il loro scopo, perciò evita abbreviazioni oscure o termini troppo generici. Nomi ben scelti facilitano la comprensione e la manutenzione del codice. Utilizza il maiuscoletto per separare le parole, il trattino o l’underscore. Ecco alcuni semplici esempi:
Nomi tipici di variabili:
customerName – Contiene il nome del cliente.
orderTotal – Rappresenta il totale dell’ordine.
numberOfItems – Indica il numero di elementi in un insieme.
Nomi tipici di funzioni:
CalculateTotalPrice – Calcola il prezzo totale degli articoli.
GetUserFullName – Restituisce il nome completo dell’utente.
ValidateEmailFormat – Verifica il formato corretto di un indirizzo e-mail.
Nomi tipici di classi:
Person – Rappresenta una persona con attributi come nome ed età.
Car – Rappresenta un veicolo a quattro ruote con attributi come marca, modello e anno.
Student – Rappresenta uno studente (derivato da Person) con attributi aggiuntivi come la relazione con la scuola ecc.
2) Scrivi commenti chiari e concisi
Commenta il codice per spiegare le sue parti complesse o fondamentali. Assicurati che i commenti siano chiari e pertinenti, evitando che risultino superflui o che possano confondere. La documentazione dovrebbe essere un’aggiunta utile, non un ostacolo.
Pensali anche tenendo conto della ricerca interna: inserire parole chiave nel commento può far risparmiare moltissimo tempo in fase di revisione.
Ecco un esempio in Python di un tipico commento.
# Calcola la somma dei primi dieci numeri interi positivi.
Ricorda che i commenti possono aiutare anche l’IntelliSense come, ad esempio, un commento sopra una dichiarazione di un metodo C# con i parametri da passare.
/// <summary>
/// Add Customer – metodo che aggiunge un Cliente
/// </summary>
/// <param name="ragioneSociale"></param>
/// <param name="partitaIVA"></param>
/// <returns></returns>
3) Cura la struttura
Organizza il tuo codice in blocchi o sezioni. Come crearne? Con rientri e spazi vuoti. Utilizza strutture di controllo come loop e condizioni per separare logicamente le parti. Una struttura ben organizzata semplifica la navigazione attraverso il codice e aiuta a trovare rapidamente le informazioni necessarie.
Noi utilizziamo Visual Studio e ci pensa lui all’indentazione. Prova a digitare CTRL K+D e vedrai magie!
Ecco un esempio di codice, sempre in Python, con rientri realizzati mediante tabulazione (in Python l’indentazione non è legata soltanto alla bellezza del codice ma ha una funzione basilare: se si sbaglia indentazione il codice avrà sicuramente comportamenti inaspettati).
def calcola_media(valori):
# Calcola la media dei valori dati in input.
totale = sum(valori)
media = totale / len(valori)
return media
def calcola_deviazione_standard(valori):
# Calcola la deviazione standard dei valori dati in input.
media = calcola_media(valori)
scarti_quadratici = [(x - media) ** 2 for x in valori]
varianza = sum(scarti_quadratici) / len(valori)
deviazione_standard = varianza ** 0.5
return deviazione_standard
# Blocco principale del programma
dati = [12, 15, 18, 10, 21, 14, 17]
media = calcola_media(dati)
deviazione = calcola_deviazione_standard(dati)
print("Media:", media)
print("Deviazione standard:", deviazione)
4) Aggiungi una documentazione dettagliata
Integra il progetto con una documentazione dettagliata per funzioni, metodi e classi. Descrivi cosa fa ciascun componente, quali parametri accetta e cosa restituisce. Utilizza uno stile di documentazione standard per garantire coerenza.
Una buona documentazione di solito fa uso di “docstring”.
Di cosa si tratta? Sono stringhe di testo collocate all’inizio di funzioni e classi che spiegano il loro scopo e utilizzo. Ad esempio, sempre in Python, qualcosa del genere:
def calcola_media(valori):
"""
Calcola la media dei valori dati in input.
Args:
valori (list): Una lista di numeri da cui calcolare la media.
Returns:
float: La media dei valori.
"""
totale = sum(valori)
media = totale / len(valori)
return media
5) Usa moduli separati
Non dimenticare di suddividere il codice in moduli o classi che svolgono funzioni specifiche.
Questa separazione rende il codice più gestibile e comprensibile perché suddivide le responsabilità tra chi dovrà lavorarci. Moduli chiari semplificano la manutenzione e l’aggiunta di nuove funzionalità.
6) Niente ridondanze
Evita la duplicazione del codice utilizzando funzioni o metodi. Questo non solo rende il codice più efficiente ma semplifica anche le modifiche future.
Un codice riutilizzabile favorisce la coerenza e la manutenibilità nel tempo. Naturalmente ottimizzare il codice evitando ripetizioni richiede più tempo e impegno, ma stai certo che il computer su cui girerà consumerà meno risorse, sarà anche più sicuro e i tuoi colleghi developer ti ringrazieranno.
7) Verifica e correggi
Includi test unitari e di integrazione per verificare il corretto funzionamento del codice. Utilizza un debugger per individuare e risolvere gli errori. Documenta i test eseguiti e i risultati ottenuti.
8) Definisci versioni del codice
Utilizza un sistema di controllo delle versioni per tenere traccia delle modifiche al codice nel tempo, attività che favorisce la collaborazione e facilita il ripristino di versioni precedenti in caso di necessità.
Un ottimo sistema di controllo delle versioni è Git. Qui trovi la documentazione per usarlo al meglio: https://git-scm.com
9) Formatta in modo chiaro
Mantieni una formattazione uniforme con uno stile coerente per parentesi, spazi e indentazioni. Una formattazione chiara rende il codice più leggibile e comprensibile.
Così come quando si parla una lingua (compresa quella madre) si ha il proprio tono di voce, anche fare coding è un po’ la stessa cosa: l’importante è mantenersi coerenti con il proprio stile e non cambiarlo.
Se ad esempio sei solito ricorrere alle tabulazioni per distanziare i blocchi, usa sempre i blocchi e non gli spazi, o viceversa. Sembra una cosa da niente ma spesso sono questi dettagli a fare la differenza. Non solo la funzionalità ma anche la percezione della cura con cui si è programmato da parte degli altri membri del team è importante.
10) Revisiona e migliora il codice nel tempo
L’ultimo consiglio che ti diamo è questo: prima di condividere il tuo codice con il tuo team, rivedilo accuratamente per assicurarti che sia chiaro e privo di errori. Chiedi feedback ai colleghi per migliorare la qualità di quanto prodotto. La revisione costante aiuta a mantenere la documentazione aggiornata e utile nel tempo.
In conclusione...
Tra coder è tipico pensare che un codice commentato e documentato in modo diverso da come lo avremmo fatto noi non sia un buon codice, ma non è sempre così. Leggere un codice non nostro significa “entrare nel mondo altrui” per comprenderne e rispettarne lo stile, auspicando sempre che sia chiaro.
D’altronde, scrivere codice non è solo realizzare un elenco di istruzioni ma anche un atto creativo e di comunicazione. E se, come dicevamo, è vero che un linguaggio di programmazione è un po’ come una lingua straniera, è anche vero che questa si può imparare studiandola, certo, ma anche praticandola, cogliendo le diverse sfumature insite nello stile di programmazione di ciascuno di noi.
Che ne pensi? Ci piacerebbe molto saperlo con un commento sui social (ad esempio sulla nostra pagina Linkedin) o, perché no, con un messaggio privato.
Speriamo in ogni caso che questo articolo ti sia stato utile per rendere più leggibile la tua programmazione e favorire una collaborazione più comprensiva e armoniosa tra te e i tuoi compagni di coding.
(1) Martin Fowler, L’arte del Refactoring. Guida alle tecniche per migliorare il design e la leggibilità del codice, Apogeo, Milano 2019.