risorse | clean code

Clean Code

A Handbook of Agile Software Craftsmanship

Una raccolta di alcuni interessanti spunti trovati nel libro, raggruppati per capitolo.

1. Clean Code

Il primo capitolo contiene la definizione di clean code secondo l'esperienza dei maggiori esperti del settore; alcune di esse sono riportate qui di seguito:

• I like my code to be elegant and efficient. The logic should be straightforward to make it hard for bugs to hide… – Bjarne Stroustrup, inventor of C++;
• Clean Code always looks like it was written by someone who cares. – Michael Feathers, author of Working Effectively with Legacy Code.
• You know you are working on clean code when each routine you read turns out to be pretty much what you expect… – Ward Cunningham, inventor of Wiki;

Si argomenta sul paradosso che il codice sporco, risultato di un'attività frenetica di sviluppo volta ad accelarare i tempi di consegna, si rivela essere in realtà una – se non la principale – causa di ritardo. Viene quindi presentata la metafora della finestra rotta, la cui morale dovrebbe spronare a ripulire il codice ogni qualvolta se ne presenti la possibilità, in particolare durante le fasi di refactoring: anche la ripulitura del codice quindi, può essere effettuata in maniera incrementale.

Viene infine proposta la regola del boyscout adattata al contesto del libro: lascia il codice più pulito di come l'hai trovato.

2. Meaningful names

I consigli proposti in questo capitolo sono piuttosto noti, e spesso si ritrovano in pubblicazioni analoghe (cfr. Pescio, Manuale di Stile C++, Fowler, Refactoring, …):

• scegliere nomi che chiariscano lo scopo delle variabili;
• sostituire i valori numerici con costanti parlanti;
• scegliere nomi che agevolino le ricerche;
• rinunciare ai prefissi (m_ per le variabili membro, I per le interfacce, C per classi, …);
• usare sostantivi per interfacce e classi, verbi o predicati per i metodi;
• nomi dal dominio della soluzione sono accettabili se usati per descrivere aspetti puramente algoritmici.

3. Functions

Anche le indicazioni riportate in questo capitolo, riguardante la scrittura delle funzioni, si trovano spesso citati in pubblicazioni simili; interessante l'idea della stratificazione delle funzioni in analogia con i livelli di astrazione delle operazioni effettuate.

• le funzioni devono essere brevi (4/5 righe al massimo);
• una funzione deve fare una cosa sola;
• le istruzioni di una funzione devono condividere lo stesso livello di astrazione: in questo modo il codice si stratifica, e ogni step-in corrisponde alla discesa al livello di astrazione sottostante;
• il numero di argomenti deve essere limitato (non più di tre); argomenti tra loro correlati possono essere aggregati in oggetti o strutture;
• evitare i flag negli argomenti, significa che la funzione assolve a due compiti diversi (meglio definire un'altra funzione);
• evitare di usare gli argomenti come valori di ritorno, non è naturale;
• evitare gli effetti collaterali;

• separare funzioni operative e interrogazioni, si generano forme ambigue:

      if (set("username", "pippo")) {
        // ???
      }
    

• preferire le eccezioni ai codici d'errore;

• isolare i blocchi try/catch in funzioni esterne; la funzione:

      void doSeveralThings()
      {
        doOneThing();
  
        try
        {
          tryToDoSomethingCritical();
        }
        catch (...)
        {
        }
  
        doAnotherThing();
      }
    

  è consigliabile riscriverla in questa forma:

      void doSeveralThings()
      {
        doOneThing();
        doSomethingCritical();
        doAnotherThing();
      }
  
      void doSomethingCritical()
      {
        try
        {
          tryToDoSomethingCritical();
        }
        catch (...)
        {
        }
      }
    

• preferire il polimorfismo ai costrutti if e switch;

• esplicitare le dipendenze temporali: se due funzioni vanno chiamate secondo un ordine determinato, fare in modo che la seconda dipenda dal risultato della prima:

      class A
      {
        B b;
        C c;
      public:
        void f() {
          first(); // calcola b
          second(); // usa b per calcolare c
          // usa c
        }
      }
    

  diventa:

      class A
      {
      public:
        void f() {
          B b = first();
          C c = second(b);
          // usa c
        }
      }
    

4. Comments

Le avvertenze sono le solite:

• definire e rispettare le regole di formattazione;
• preferire il codice autoesplicativo (rifattorizzare piuttosto che commentare);
• evitare commenti ridondanti o fuorvianti; fare attenzione all'obsolescenza dei commenti;
• rimuovere il codice commentato;
• non usare i commenti per registrare le attività svolte: usare un sistema di controllo dei sorgenti.

5. Formatting

Anche in questo caso non ci si discosta da ciò che si trova in letteratura:

• ordinare le funzioni per livello di astrazione (il chiamante prima del chiamato);
• minimizzare la distanza verticale tra funzioni affini;
• minimizzare la distanza verticale tra dichiarazione e uso delle variabili;
• separare con una riga vuota i segmenti di codice fortemente correlati;
• il limite delle 80 colonne è superato, ma meglio non esagerare (suggerisce 120);

• evitare gli allineamenti orizzontali:

    int                current_page;
    std::vector<int>   pages;
    bool               is_published;
    std::string        header;
   

  questo tipo di formattazione induce una suddivisione tra i tipi (a sinistra) e le variabili (a destra) anziché l'associazione di ogni variabile col suo tipo.

6. Objects and Data Structures

Il sesto capitolo affronta la dicotomia oggetti/strutture, affermando che se l'interfaccia dei primi deve astrarre dall'implementazione, per le seconde ciò non vale, essendo dei semplici contenitori di dati. Seguono due considerazioni:

• preferire oggetti a strutture rende semplice aggiungere nuovi oggetti;
• preferire strutture a oggetti rende semplice aggiungere nuove funzioni.

La tesi viene suffragata considerando che l'introduzione di una nuova entità all'interno di una gerarchia di classi si ottiene derivando la nuova entità da una esistente ed implementandone le funzionalità specifiche; nel caso di una gerarchia di strutture, è necessario intervenire su tutte le funzioni operanti sulle strutture esistenti, dovendo esse ora trattare anche la nuova casistica. Viceversa, l'introduzione di una nuova funzionalità in una gerarchia di classi spesso si traduce nell'aggiornamento dell'interfaccia di gran parte delle classi esistenti; nel caso di strutture, normalmente è sufficiente implementare la nuova funzionalità in un metodo globale.

Limitatamente al dominio degli oggetti, viene citata la legge di Demeter, e viene proposto un metodo per soddisfarla, che consiste nell'esporre parte della funzionalità del contenuto nell'interfaccia del contenitore:

   final String outputDir = ctxt.options.scratchDir.absolutePath;
   ...
   String outFile = outputDir + "/" + className.replace('.', '/') + ".class";
   FileOutputStream fout = new FileOutputStream(outFile);
   BufferedOutputStream bos = new BufferedOutputStream(fout);

si può rendere meglio così:

   BufferedOutputStream bos = ctxt.createScratchFileStream(classFileName);

7. Error Handling

• la gestione dell'errore non deve nascondere la logica del codice;
• le eccezioni devono fornire informazioni circa il contesto dal quale provengono;
• non ritornare null; meglio sollevare un'eccezione oppure ritornare un oggetto special case in grado di gestire il caso anomalo;
• non passare null come argomento, è sintomo di flag; meglio definire due funzioni o passare uno special-case.

8. Boundaries

L'ottavo capitolo è dedicato alla gestione dei confini del proprio codice, ovvero come rendere il codice di nostra competenza robusto rispetto alla variabilità e alla disponibilità di librerie di terze parti o di codice sviluppato da altri colleghi. Il suggerimento principale è il ricorso al wrapping.

Librerie di terze parti:

• disaccoppiare il codice dalle API proprietarie per mezzo di wrappers;
• se la documentazione fornita con la libreria non è sufficientemente affidabile, o se il suo comportamento non è stabile nelle versioni che si succedono, può risultare conveniente sviluppare unit test per determinarne il reale funzionamento (learning tests);

Relativamente al codice sviluppato da altri colleghi, qualora questo non sia ancora disponibile, si raccomanda l'uso di mock/stubs per emulare le funzionalità necessarie; questi potranno in seguito essere riutilizzati come adapter dei componenti reali, quando diventeranno disponibili.

9. Unit Test

Il capitolo inizia enunciando le tre leggi del TDD:

1. non si scrive codice di produzione finché un test non fallisce;
2. non si scrive codice di test se non quello necessario al fallimento (un errore di compilazione è già di per se un fallimento);
3. non si scrive codice di produzione se non quello necessario per far passare il test che fallisce.

Il TDD costringe lo sviluppatore a passare continuamente dallo scrivere codice di test – che fallisce – alla scrittura di codice di produzione – che fa passare il test. Il codice progredisce così per piccoli passi, essendo la durata tipica di un ciclo di qualche minuto. Risulta perciò quasi impossibile perdersi nel codice dato che, per definizione, se a un dato momento il test non passa la causa è da ricercare nelle modifiche introdotte nell'ultima iterazione. Ciò regala una notevole serenità al programmatore, che ha la certezza che, qualunque cosa sia successa, pochi undo lo ricondurranno ad una situazione stabile.

Il codice di test va trattato come il codice di produzione. Cosa fa invece di un test case un buon test case?

• deve emergere chiaramente la struttura build-operate-check (o AAA: arrange-act-assert);
• deve considerare un unico aspetto dell'oggetto in test;
• deve essere rapido, indipendente, ripetibile rispetto all'ambiente di esecuzione, auto-validante (deve fornire una chiara indicazione circa il successo o il fallimento);

La copertura del codice di produzione deve essere totale: deve essere testato tutto ciò che in linea di principio potrebbe fallire; non si devono trascurare nemmeno le funzionalità più banali (se non altro, è documentazione).

10. Classes

Oggetto di questo capitolo sono le classi; vengono rispolverati i più importanti principi della progettazione object-oriented:

• Single Responsibility Principle: per una classe deve esistere un unica ragione perché debba essere modificata;

• Open/Close Principle: una classe deve essere aperta alle estensioni, ma chiusa alle modifiche;
• Dependency Inversion Principle: si deve dipendere dalle astrazioni, non dai dettagli.

Non ci si deve spaventare di fronte ad una moltitudine di piccole (super-focalizzate) classi rispetto a poche, vaste classi: essendo le funzionalità implementate le medesime, medesima è la quantità di concetti da gestire e comprendere.

Una classe deve essere coesa:

• deve possedere pochi membri fortemente correlati;
• deve esporre pochi metodi che manipolano i membri (più membri un metodo manipola, più il metodo è coeso alla classe);

Un'osservazione interessante è la seguente: favorire la coesione porta all'aumento del numero di classi.

11. Systems

Il capitolo è molto java-oriented, essendo particolarmente focalizzato sull'AOP.

Alcune osservazioni di carattere generale sono dedicate all'inizializzazione del sistema software, inteso come istanziazione degli oggetti principali. Vengono presentate tre differenti tecniche di start-up del sistema software:

• il main decide cosa costruire, e quando;
• il main decide cosa costruire, il codice quando (è un esempio di lazy initialization, realizzabile ad esempio per mezzo di oggetti factory);
• l'applicativo decide cosa costruire, quando (tramite dependency injection).

12. Emergence

Vengono descritte e commentate le regole del simple design, riportate qui sotto nella loro forma originale:

1. runs all the tests;
2. no duplication;
3. express developer intent;
4. minimizes the number of classes and methods.

Una volta ottemperato alla prima regola, il refactoring consente di realizzare le successive.

Riferimenti

Martin, Robert C. Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall, 2008.

Pagina modificata l'8/11/2011