Codice pulito: la trappola in cui non devi cadere

Questo post nasce da un’esperienza avuta recentemente con un cliente e riguarda una truffa di cui purtroppo è stato vittima.

Questo cliente stava cercando di sviluppare internamente alla sua azienda un software in grado di controllare un robot industriale che fosse in grado di fare particolari misurazioni per la sua catena di montaggio. Non avendo programmatori interni all’azienda con gli skill tecnici necessari ad affrontare il problema ha quindi deciso di commissionare lo sviluppo del sorgente ad una software house esterna, che poi avrebbe rilasciato tutto il progetto (compilato + sorgente) all’azienda.

Mai errore gli fu più fatale, ed ora ti spiego il perchè.

Nelle varie clausole del contratto e negli accordi verbali tra le parti era specificato che il codice dovesse essere pulito e commentato in modo da poter permettere agli sviluppatori interni di poter fare modifiche in un secondo momento, senza dover per forza appoggiarsi alla software house che ha sviluppato il progetto iniziale.

Ma proprio questa clausola è stata il motivo per cui l’azienda si è ritrovata a richiedere la mia consulenza esterna.

Parlare di codice pulito, senza definirne prima le regole è un errore che nella totalità dei casi fa molto male alla tua azienda ed al tuo progetto.

Dire che un codice pulito è come dire che una canzone è bella: ovviamente tutto dipende da chi ascolta. Qualcuno potrà identificare la canzone come la più bella del mondo, altri invece potrebbero non capirne le strutture dei versi, o il ritmo particolarmente ricercato. Se però tutto viene giustificato in un documento progettuale, tutti quelli che possono essere interpretati come parametri soggettivi vanno ad assumere una valenza assoluta ed oggettiva. E ovviamente se la progettazione ha un senso logico corretto nessuno potrà mai dire di non essere concorde con essa.

L’importanza di avere un eccellente documento di progettazione

Progettare un software applicativo (che sia esso un sito web o un software per il controllo di una centrale nucleare) richiede sostanzialmente gli stessi skill di progettazione (attenzione: progettazione, non realizzazione), skill che vanno evidenziati in un documento che deve essere assolutamente creato a bocce ferme, prima di scrivere qualsiasi riga di codice.

In informatica l’ordine è la cosa più importante in assoluto, ordine che viene sintetizzato quasi totalmente nel design pattern che verrà adottato.

Di design pattern ne esistono di moltissimi tipi, senza dubbio i più comuni sono il design MVC (model view controller) e recentemente si sta diffondendo molto il design MVO (model view observer) usati soprattutto per le progettazioni di applicativi dotati di interfaccia.

In alcuni casi può essere necessario sviluppare una strategia diversa, creando un design pattern ad hoc per il progetto.

In questi casi, come è stato per il mio cliente, è fondamentale descrivere nei minimi dettagli la strategia di sviluppo adottata nel documento di progettazione, al fine che chiunque possa aver ben chiaro come si articola il progetto ed in quanti componenti sarà diviso.

Altri due passi fondamentali da inserire nel documento di progettazione di un software sono:

• le regole sintattiche
• la posizione ad eventuali aperture di sviluppo

Le regole sintattiche di un software

Dopo aver stabilito quale linguaggio di programmazione utilizzare per sviluppare l’applicazione è fondamentale stabilire le regole sintattiche interne che tutti gli sviluppatori che partecipano al progetto dovranno adottare.

Ad esempio noi adottiamo le seguenti regole (indipendentemente dal linguaggio adottato):

• le costanti vanno dichiarate in MAIUSCOLO
• le variabili a visibilità globale vanno dichiarate con l’underscore davanti e una sintassi parlante camelCase (ad esempio _velocitaX)
• le variabili di funzione vanno dichiarate con sintassi parlante camelCase (ad esempio numeroCicli)
• tutte le variabili e le costanti vanno dichiarate nel punto più in alto relativo alla loro visibilità (le globali e le costanti dopo le inclusioni di classe e le locali all’inizio della funzione)
• le funzioni devono avere una sintassi parlante camelCase (ad esempio function disegnaRettangolo())
• anche le variabili di ciclo (ad esempio le variabili usate nei cicli for()) vanno dichiarate in alto (generalmente nella funzione) e non all’interno del ciclo come avviene comunemente

Queste semplici regole donano al codice pulizia e leggibilità e se inserite correttamente all’interno di un documento di progettazione permettono a chiunque di poter interpretare il codice e capire dove sono situati eventuali bug.

La posizione ad eventuali aperture di sviluppo

Eseguire implementazioni all’interno di un software, aggiungendo feature, non è spesso un’operazione di facile esecuzione, soprattutto se il codice è poco documentato.

In questi casi è fondamentale specificare nel documento di progettazione gli hook (i ganci) a cui attaccarsi per implementare nuove funzionalità.

Spesso questi punti di accesso coincidono con delle API, che possono essere chiamate e modificate a seconda delle esigenze, ma questo non è sempre possibile. Nel caso di software compilati in cui non sono presenti API e  che magari necessitano di ottimizzazioni particolari è fondamentale stabilire quali sono le funzioni forti e quelle deboli.

Per funzioni forti si intendono tutte quelle funzioni in cui l’ottimizzazione è spinta a livelli talmente alti per cui l’implementazione di ulteriori cicli, o allocazioni di memoria rischia di inficiare le performance dell’intera struttura.

Le funzioni deboli viceversa sono tutte quelle funzioni o procedure in cui si ha ancora spazio di movimento e l’implementazione di una nuova funzionalità non va a pesare sul risultato finale. Queste sono le posizioni in cui è consigliabile lavorare. Ovviamente queste porzioni di codice devono essere specificate nel documento tecnico di progettazione, per evitare di generare incomprensioni o di creare danni strutturali a livello di codice.

Nel caso in cui questi hook non siano specificati l’approccio consigliato è quello di creare un side software, ovvero un programma che si interfaccia al primo dialogando attraverso dei ponti software (essi siano condivisioni di piccole aree di memoria, files o comunicazioni di rete) estendendo le funzionalità del software principale.

Ma la cosa più importante sono i commenti

Di sicuro in tutta questa trattazione abbiamo visto tanti diversi approcci per scrivere (e far scrivere) software leggibile e pulito, ma bisogna ricordare di non trascurare mai i commenti.

E per i commenti esiste una sola regola: devono essere essenziali e quando presenti devono realmente spiegare una qualcosa di importante. Quindi ben vengano pochi commenti ben approfonditi quando servono.

E ovviamente l’ultimo consiglio, se non fosse ancora ovvio: quando si sviluppa (o si fa sviluppare) un software è fondamentale partire da un buon documento progettuale, altrimenti si rischia di buttare inutilmente tempo e denaro.