Java: Codice pulito e coerente con Checkstyle

J

Code conventions

Le convenzioni sul codice sono importanti per i programmatori per tutta una serie di motivi:
• L’80% del costo della vita di un software va alla manutenzione.
• Quasi nessun software viene mantenuto per tutta la sua vita dall’autore originale.
• Le convenzioni sul codice migliorano la leggibilità del software, consentendo agli engineers di comprenderne il codice più rapidamente e accuratamente.
• Se consegni il tuo codice sorgente come prodotto, devi assicurarti che sia ben strutturato
e pulito come qualsiasi altro prodotto.

Gli ingegneri della SUN hanno pubblicato da molti anni Java Language
Specification, from Sun Microsystems il quale contiene gli standard che dovrebbe avere un buon codice Java. Purtroppo queste linee guida non sono molto state utilizzate dalla community mondiale dei developer java: per la paura di perdere tempo molti developer ignorano il chiaro vantaggio di avere un codice conforme alle linee guida; il risultato è codice poco leggibile (quante volte avete maledetto sviluppatori che scrivono linee di codice da 200 caratteri ?!), soggetto a regressioni e bug.

review del codice

Il code review è la fase del processo di sviluppo del software nella quale i membri del team si riuniscono per revisionare una o più parti del codice. Per capirci meglio illustro un possibile scenario di un team di sviluppo il quale utilizza come sistema di versioning GIT:

  • Marco è un membro del team che prende in carico una task di sviluppo e crea un branch ad hoc per la feature o il bug da fixare.
  • Non appena Marco ha completato lo sviluppo della task esegue il commit, e fa il push del branch creato per la feature in oggetto di sviluppo.
  • Marco effettua una pull request del branch sviluppato, in modo da avvertire il project manager e gli altri membri del team che ha completato gli sviluppi della task.
  • Uno o più membri del team validano il codice scritto da Marco in termini di correttezza ma anche di stile del codice prodotto. Se il codice di Marco è corretto e ben scritto la pull request viene approvata e viene effettuato il merge della feature sviluppata.

L’ ultimo punto citato è una fase decisamente costosa; se una pull request di uno sviluppatore viene declinata più volte per motivi di stile (motivi facilmente prevenibili dal developer) il processo di sviluppo viene decisamente rallentato. Occorre minimizzare la possibilità di consegnare alla review codice non conforme alle linee guida del team in modo da massimizzare la probabilità di superare la review del codice e quindi i tempi di sviluppo. Per questo motivo nasce Checkstyle.

checkstyle

Checkstyle è uno strumento di sviluppo per aiutare i programmatori a scrivere codice Java conforme a delle code conventions ben definite. Automatizza il processo di controllo del codice Java per risparmiare ai developer questo compito noioso ma importante, come ben sottolineato ad inizio articolo.

Il team di progetto deve decidere le code conventions del codice a cui si devono adeguare tutti i developer, ad esempio:

  • lunghezza massima linee di codice
  • javadoc obbligatori?
  • proibire i magic number
  • regole di naming di variabili e costanti
  • e altre rules

Una volta decise queste rules occorre configurare Checkstyle per eseguire questi controlli. Checkstyle si configura con un semplice documento XML i cui elementi specificano la gerarchia della configurazione dei moduli e i check a cui è sottoposto il codice (immaginatevi  un tag per ogni check).

Riportiamo una configurazione minimale:

<module name="Checker">
  <module name="TreeWalker">
    <module name="AvoidStarImport"/>
    <module name="ConstantName"/>
    <module name="EmptyBlock"/>
  </module>
</module>

Andiamo ad analizzare il documento xml riportato:

  • Il modulo Checker è la root la quale deve essere sempre presente.
  • Il sotto modulo TreeWalker è il modulo dove vengono inseriti i check a cui è sottoposto il codice. TreeWalker opera trasformando separatamente ciascuno dei file sorgente Java in un albero di sintassi astratto e quindi passando il risultato a ciascuno dei suoi sottomoduli figli per le validazioni.
  • Figli di TreeWalker : nellèesempio mostrato il codice + sottoposto a i seguenti check:
    • AvoidStarImport: controlla che non ci siano import che usano la notazione *
    • ConstantName: Controlla che i nomi delle costanti (variabili dichiarate sia static che final) siano conformi al formato specificato. Se nessun formato viene specificato viene utilizzato il consueto pattern “^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$” (ad esempio una dichiarazione corretta potrebbe essere public static final SUB_CODE = 10;)
    • EmptyBlock: controlla che non ci siano blocchi vuoti di codice.

Esistono una miriade di controlli configurabili tramite appositi tag checkstyle. Per un elenco completo rimando alla documentazione ufficiale: LINK 

Una volta configurato il checkstyle ci sono diverse opzioni per utilizzarlo:

  • È possibile configurare il checkstyle per essere eseguito automaticamente da gradle o maven. Consiglio la lettura dei seguenti link:
  • Se il team fa uso di continuos integration con tool come Jenkins è possibile inserire nella pipeline uno step di validazione del codice (ad esempio con Jenkins: LINK3)
  • Ancora più semplicemente è possibile utilizzare checkstyle all’interno del proprio IDE (sia Eclipse che Intellij hanno appositi plugin per checkstyle).

Ad esempio io ho installato sul mio Intellij il checkstyle plugin

Dal menu di Intellij: File -> Other Settings -> Checkstyle ho importato il mio template xml di checkstyle e l’ho selezionato come configuration file attivo. A questo punto posso eseguire quando voglio un report di controllo codice su un file o sull’intero progetto. Ad esempio riporto uno screenshot di un report checkstyle che evidenzia problemi di stile di una mia classe.

configurare il proprio xml

Come configurare il file xml di controllo di checkstyle? Quali check introdurre al suo interno? Non esiste una risposta corretta a questa domanda; i controlli e code conventions a cui deve essere sottoposto il codice sorgente di un progetto dipendono dalle esigenze e rigidità del team. Ad esempio un progetto open-source avrà un file di configurazione checkstyle più rigido mentre ad esempio un team di poche persone potrebbe necessitare di rules meno rigide (ad esempio javadoc non obbligatori per ogni funzione). Google e Oracle hanno condiviso il file checkstyle che utilizzano al loro interno per produrre codice pulito e di qualità:

Il mio consiglio è quello di partire da uno di questi template, andando via via ad eliminare i check troppo rigidi per il vostro team. Condivido anche il checkstyle che solitamente uso: un buon compromesso per un codice pulito senza troppe difficoltà dovute alla rigidità dei template sopra riportati, che possono essere un over-head per progetti non open-source: LINK.

 

 

A proposito di me

Dario Frongillo

Software architect con un forte background in Java, Architettura REST, framework Spring , Database Design,progettazione e sviluppo di SPA e RIA Web application con framework Javascript. Attualmente mi occupo di sviluppo soluzioni software in ambito Banking e Finance: in particolare progettazione e sviluppo di applicativi web based per la realizzazione di sistemi di trading, interfacce con i mercati finanziari e di servizi real time.

Gli articoli più letti

Articoli recenti

Commenti recenti