#Blog

Colleague-based Testing

Un approccio alternativo per mantenere la leggibilità.

27/01/2025

Per garantire una maggiore leggibilità, i post del blog rispecchiano il font di default impostato dal sistema, anziché il comune Press2Start presente nel resto del sito.

🇬🇧 Are you looking for the english version? Click here

🚀 Il test di leggibilità che (forse) stai trascurando: il tuo codice è comprensibile per gli altri?

Come sviluppatori, spesso ci concentriamo sull’assicurarci che il nostro codice funzioni - che venga compilato, che superi i test e soddisfi i requisiti. Ma c’è un altro aspetto altrettanto importante: fare in modo che il nostro codice sia leggibile. Se il tuo codice non è facile da capire, stai creando debito tecnico per i futuri sviluppatori - e forse anche per il tuo futuro te stesso. Ma come si misura qualcosa di soggettivo come la leggibilità? Un modo semplice e molto efficace è testare il tuo codice con i colleghi.

Perché testare la leggibilità del codice?

Quando parliamo di test del software, solitamente ci riferiamo a unit test, test di integrazione o end-to-end test. Ma il codice è anche un messaggio rivolto ad altri sviluppatori, non solo un insieme di istruzioni per le macchine. Se vuoi verificare che il tuo codice sia chiaro quanto pensi, prova questo:

  1. Chiedi ai colleghi: Durante una code review o una discussione informale, verifica se il tuo team riesce a spiegare cosa fa un pezzo di codice senza alcuna spiegazione aggiuntiva da parte tua.
    Se faticano a descrivere la funzionalità, è un segnale che potresti dover rinominare variabili e metodi, semplificare la logica o aggiungere commenti concisi.

  2. Controlla i nomi dei tuoi test: Sono abbastanza descrittivi da spiegare perché stai testando qualcosa? Ad esempio,

    it('should calculate average excluding invalid votes')

    è molto più informativo di test case 18. Un test ben nominato può fungere da documentazione autonoma.

Questo tipo di “test di leggibilità” assicura che il tuo codice non sia solo corretto, ma anche comprensibile - e questo può ridurre notevolmente i costi di manutenzione futuri.

Consigli pratici per migliorare la leggibilità

Ecco alcune strategie che ti aiuteranno a superare alla grande il “test di comprensione tra colleghi”:

1. Usa nomi significativi

  • Variabili & Funzioni: Dai nomi chiari e descrittivi che comunichino l’intento. Al posto di data o val, meglio studentRecords o averageScore.
  • Classi & Metodi: Un metodo chiamato processData() può andare, ma filterOutInvalidData() o calculateCustomerDiscount() è molto più specifico.

2. Mantieni le funzioni focalizzate

  • Single Responsibility Principle: Ogni funzione o metodo dovrebbe avere un solo compito. Se qualcuno che legge la tua funzione fa fatica a capirla, probabilmente stai gestendo troppe cose in un solo posto.
  • Scomponi la logica: Le funzioni molto lunghe possono spesso essere suddivise in metodi più piccoli e ben nominati.

3. Lascia indizi, non saggi

  • Commenta ciò che non è ovvio: Un eccesso di commenti può essere dannoso quanto averne troppo pochi. Se nomi di variabili e firme di funzione sono chiari, non serve un paragrafo per descriverli. Ma se c’è un calcolo complesso o una logica particolare di dominio, un breve commento può essere utilissimo.
  • Tieni i commenti aggiornati: Un commento obsoleto è peggio che non avere alcun commento, perché crea confusione.

4. Scrivi test che spieghino il “perché”

  • Descrivi i casi d’uso nei nomi dei test: Ad esempio, test_calculate_total_price_including_taxes() fa subito capire cosa viene validato.
  • Usa descrizioni nei test: Se il tuo test runner lo consente, scrivi messaggi descrittivi. Aiutano chi manterrà il codice in futuro a capire perché un test fallisce e cosa deve essere corretto.

5. Le code review come barometro di leggibilità

  • Incoraggia il feedback: Durante le review, chiedi esplicitamente: “È chiaro l’intento del mio codice? Potresti spiegarmelo a parole tue?”
  • Itera e migliora: Se il tuo revisore deve chiedere cosa significhi qualcosa, prendi in considerazione l’idea di rinominare o rifattorizzare. Vedi ogni richiesta di chiarimento come un’opportunità per perfezionare il tuo approccio.

L’esperimento del “Colleague-based Testing”

Uno dei modi migliori per testare la comprensibilità del tuo codice è prendere un frammento - possibilmente qualcosa di nuovo o un po’ complesso - e mostrarlo a un collega. Poi chiedi:

“Puoi dirmi, leggendolo, cosa pensi che faccia?”

Non offrire spiegazioni o chiarimenti in anticipo. Lascialo leggere il codice e parafrasare ciò che vede. Se la descrizione risulta quasi corretta, complimenti! Il tuo codice probabilmente è ben scritto. Se invece trova delle difficoltà, annota i punti di incertezza: forse i nomi delle variabili non sono sufficientemente espliciti, o la logica è troppo intricata. Questo scambio di feedback è fondamentale per migliorare la chiarezza del codice.

Che vantaggi ne ricavi?

All’inizio, dedicare tempo per scrivere codice leggibile può sembrare un extra, ma a lungo termine porta numerosi benefici:

  • Onboarding più rapido: I nuovi membri del team imparano in fretta se possono capire la base di codice senza troppe fatiche.
  • Manutenzione più semplice: Quando emergono bug - o devi aggiungere nuove funzionalità - il codice leggibile ti fa risparmiare ore di decifrazione.
  • Migliore collaborazione: Le code review sono più efficaci se il revisore può concentrarsi sulle questioni più rilevanti invece di dover chiedere chiarimenti basilari su nomi o intenti.

A te la parola: tu testi la leggibilità?

In fin dei conti, scrivere codice per gli umani è importante quanto scriverlo per le macchine. Spesso dimentichiamo che qualcun altro leggerà il nostro codice - magari domani, magari tra un anno. Applicando il “colleague comprehension test”, ti assicuri che il tuo codice non sia solo funzionante, ma anche trasparente e manutenibile.

❓ Come fai a garantire che il tuo codice sia leggibile?
Hai mai testato esplicitamente il tuo codice con un collega per capire se fosse chiaro? Lascia un commento e condividi la tua esperienza o i tuoi consigli. Le tue idee potrebbero ispirare una discussione costruttiva e aiutare altri sviluppatori a scrivere codice più pulito e leggibile!

🔎 Pro Tip: La prossima volta che fai una code review, aggiungi un passaggio in più:
“Spiegami a parole tue cosa fa questo codice.”
È un test rapido e pratico che può rivelare molto sulla chiarezza del tuo codice.

Pronto ad agire?

➡️ Prova questo esperimento nel tuo progetto attuale - potresti sorprenderti scoprendo dettagli sul tuo stesso codice.
✅ Rifattorizza le parti poco chiare - il tuo te stesso di domani (e i tuoi colleghi) te ne saranno grati.

Ricorda, la chiarezza è la chiave per la sostenibilità nello sviluppo software. Buon coding!

P.S. Questo articolo è stato scritto con il supporto dell'intelligenza artificiale.
Torna alla home