Molto spesso, quando ci si trova a sviluppare un qualsiasi progetto, magari con tempistiche piuttosto strette, capita di dare maggior importanza al far funzionare quanto creato piuttosto che alla pulizia e logica del codice stesso.
Questo è un errore più comune di quanto si pensi e capita a tutti (come ci confermano anche i nostri developer) ma, essendo di base una pratica molto controproducente, in questo articolo ti spiegheremo in 5 punti come scrivere del codice pulito, chiaro e facilmente gestibile anche nel futuro.
Chiaramente sono linee guida generali, che possono tuttavia essere adattate alla quasi totalità dei progetti e che, seppur richiedano un minimo di impegno all’inizio, una volta usate diventano lo “standard”, alzando così la tua asticella della qualità del codice.
5 best practices per un codice pulito
Punto 1: naming
Quante variabili, campi e proprietà dichiariamo al giorno? Praticamente infinite.
Tuttavia, anche in uno dei passi più semplici della programmazione, si nascondono potenziali insidie per la qualità e leggibilità del tuo codice.
Spesso si ha l’abitudine di nominare variabili e campi di tabelle usando gli acronimi, del tipo “$sdbt” o “adft”, ma questo è praticamente una zappa sui piedi ad ogni riga scritta.
Ciò che consigliamo è invece di usare sempre nomi “parlanti” quando setti il nome di una variabile, di un campo o tabella nel DB, di una proprietà o di una classe, ovvero dei nomi che in un decimo di secondo portino a capire il contenuto di quella variabile.
Quindi se stiamo definendo una variabile che conterrà un semplice id numerico, riferito ad un utente, sarà preferibile “$user_id” piuttosto che “$i” o “$index”.
Bisognerebbe essere anche specifici in base al tipo di dato conservato nella variabile stessa, ad esempio se l’id fosse di un tipo intero, il nostro “$user_id” potrebbe andar bene, ma se invece l’id fosse una stringa, come una nomenclatura che deve essere univoca nella tua tabella, è bene esplicitarlo nella variabile, chiamandola magari in modo che richiami cos’è quell’id.
Se fosse ad esempio il codice fiscale di una persona, non chiamarlo sempre “$user_id”, chiamalo invece “$cod_fiscale”, non “$cf”.
Scrivere i nomi delle variabili per acronimi sembrerà farti risparmiare tempo nell’immediato, ma prova a ricordarti tornando su quel progetto tra un anno tutti i significati delle stesse.
Punto 2: i commenti sono tuoi amici
I commenti, croce e delizia di qualunque sviluppatore che approdi su un nuovo progetto già iniziato da terzi.
Spesso capita di sperare di trovare commenti e restare delusi; per risparmiarsi questo crudele destino è necessario improntarsi verso una buona pratica che eviti spiacevoli sorprese in futuro.
Il commentare adeguatamente il codice che produci ha infatti un doppio vantaggio, sia per te stesso (perché prima o poi ti dimenticherai a cosa serviva quel metodo che hai scritto 3 anni prima), sia per i membri del tuo team, attuali o futuri.
Quando si scrive del codice, va scritto sempre come se fosse un qualcosa che facciamo per gli altri, avere la presunzione di scriverlo e leggerlo solo noi stessi è totalmente errato.
Detto questo, limitati a commentare bene tutto ciò che fai, un metodo particolare, una parte dello stesso articolata, dando informazioni utili al lettore di turno che gli permettano di comprendere il life cycle di tutto ciò che hai creato a colpo d’occhio.
Solo così otterrai qualcosa di realmente leggibile e riutilizzabile e fare manutenzione un domani sarà un gioco da ragazzi.
Il prezzo da pagare? È gratis, costa pochi minuti delle tue giornate!
Punto 3: suddividi le funzionalità
Questo è un problema diffuso soprattutto tra neofiti che partono da un approccio magari procedurale passando alla OOP.
Quando si costruisce l’architettura di un progetto, con le sue classi, le sue cartelle, i suoi namespace e similari bisognerebbe sempre ricordarsi di suddividere ogni componente in modo logico, in base alla sua specifica funzione.
Se ad esempio vogliamo creare una classe “Users” essa dovrebbe gestire solo le informazioni derivate dagli utenti e manipolare i dati degli stessi.
Se poi il nostro progetto fosse un gestionale nel settore automotive, dove dovremmo anche manipolare dati di automobili (anche associate agli utenti), servirebbe una seconda classe “Cars”, evitando di definire n mila metodi dentro la prima classe.
Questa è una divisione totalmente semplificata, tuttavia rende bene l’idea e ci aiuta almeno per due tipologie di problemi:
1. Se dovessimo modificare per qualche motivo la parte che gestisce le automobili non ci troveremmo a lavorare su un’unica classe e se siamo in un team potremmo occuparci solo della parte di competenza, evitando conflitti di sorta (c’è chi al sentire “git merge” fugge in preda al panico);
2. Aiuta il nostro cervello ad organizzare meglio il progetto a livello mentale: avendo blocchi funzionali divisi, il tutto non sembrerà un agglomerato informe di codice e sarà anche più facile da debuggare.
Punto 4: evita i monoliti
Questo punto è fratello del punto precedente, sempre parlando di suddivisione, la stessa dovrebbe essere applicata anche tra i metodi di una medesima classe.
Tantissime volte vediamo metodi da 1000 e più righe occuparsi di un gran numero di attività diverse; questo è totalmente sbagliato poiché la manutenzione di questi giga metodi è priva di ordine mentale e questo ci espone a bug di sorta. Inoltre, avere n piccoli metodi, ognuno con una funzione ben specifica, ci aiuta a riutilizzarli in modo intelligente all’interno del nostro codice.
Suddividi i tuoi metodi in base al loro scopo e vedrai quanto codice riuscirai a riutilizzare nelle tue applicazioni, semplicemente richiamando il metodo che ti serve da dove serve, ad esempio:
Approccio monolitico:
public function getCarsFullData($id_concessionaria){
// Verifico l’esistenza dell’id della concessionaria nel DB per usarlo in una condizione
// Se la concessionaria esiste eseguo una query per trovare tutte le automobili presenti per quella concessionaria suddividendo le benzina dalle diesel ed estraendo tutti i dati
// Con un ciclo manipolo la response del DB e aggiungo un elemento “offerta = true” per le macchine diesel, settando “offerta = false” per quelle benzina;
// Ritorno la JSON response del metodo
}
Approccio corretto:
public function getFullCarsData($id_concessionaria){
// Controllo l’esistenza della concessionaria in DB per usarlo in una condizione
if($this→checkConcessionaria($id_concessionaria)){
……….
//Se la concessionaria esiste eseguo una query per trovare tutte le automobili presenti per quella concessionaria suddividendo le benzina dalle diesel ed estraendo tutti i dati
$response = $this→getAllCars($id_concessionaria);
// Con un ciclo manipolo la response del DB e aggiungo un elemento “offerta = true” per le macchine diesel, settando “offerta = false” per quelle benzina, ritornando dal metodo una json response, evitandomi di farlo in questo metodo.
return $this->addOffertsData($response);
}
Suddividendo a questo livello, otteniamo 3 metodi distinti chiamati dal primo, che potranno essere utilizzati anche in altri punti del codice, lasciando il nostro metodo estremamente leggibile e soprattutto corto.
Punto 5: la documentazione
Una buona norma da sfruttare è quella di scrivere sempre una documentazione del progetto, che scenda abbastanza nel dettaglio di tutti i flussi coinvolti.
Puoi usare tranquillamente mezzi free come draw.io per creare il tuo diagramma, ci perderai un po’ di tempo ma quando avrai finito troverai senz’altro utile ciò che hai fatto.
Questa vista dall’alto ti consentirà (e consentirà agli altri) di capire il life cycle di tutta l’applicazione senza nemmeno guardare il codice, permettendoti di riflettere su eventuali modifiche, aggiunte o rimozioni ancor prima di scrivere una nuova riga.
Spesso questi diagrammi aiutano anche a suddividere meglio i componenti di un progetto, perché senza questo tipo di vista il tutto potrebbe risultare meno chiaro, mentre vedendo l’insieme è facile accorgersi se una o più funzionalità siano al posto giusto o potrebbero essere unite / divise per una logica migliore.
