Come formattare e commentare il proprio codice?
È un dato di fatto: I programmatori sono persone concrete, di sostanza, che spesso preferiscono non approfondire questioni “futili” come aspetto, stile e formattazione del markup su cui lavorano.
In realtà la formattazione del codice fa si che quest’ultimo diventi più intuitivo – per te stesso e soprattutto per le persone con cui collabori – e l’utilizzo di commenti può aiutarti a comprendere le funzionalità del codice sviluppato anche a distanza di anni, rendendo di fatto più semplice la gestione dello stesso.
Ovviamente esistono diversi approcci nella formattazione del codice e se lavori da tempo nello sviluppo probabilmente avrai già perfezionato un tuo personale modo di lavorare e di gestire il markup. In questo articolo vedremo insieme qualche piccola best practices capace di ottimizzare il tuo lavoro e di renderlo più semplice e comprensibile.
Prima di tutto, occupiamoci della formattazione. Migliorare la leggibilità del codice è molto importante e per farlo possiamo avvalerci di alcune semplici linee guida. Niente di particolarmente difficile, basta seguire alcuni piccoli accorgimenti durante il processo di sviluppo.
Indentazione
Una delle prime linee guida riguarda sicuramente l’indentazione del codice.
Indentare il codice in modo corretto, con qualsiasi linguaggio si lavori, è una delle pratiche essenziali per rendere il codice visivamente più comprensibile.
Vediamo un esempio:
//Codice non indentato
if($myVar)
{
if($myVar == 3)
{
echo ‘myVar is 3’;
}
}
else
{
echo ‘myVar is false’;
}
Come puoi vedere, in questo modo comprendere il codice che abbiamo analizzato è piuttosto difficile. Basterebbe indentarlo correttamente per renderlo molto più leggibile:
//Codice indentato
if($myVar) {
if($myVar == 3) {
echo ‘myVar is 3’;
}
} else {
echo ‘myVar is false’;
}
Per l’indentazione è consigliabile utilizzare gli spazi al posto delle tabulazioni così da aumentare la portabilità su sistemi e computer differenti. Qualunque editor ha un’impostazione che permette di sostituire il carattere di tabulazione con un certo numero di spazi, di solito 4 o 2.
Parentesi graffe
Esistono vari stili per l’utilizzo delle parentesi graffe, scegli tu quello che preferisci, non fa differenza per la leggibilità. I seguenti sono i più comunemente utilizzati:
- Le parentesi vengono allineate verticalmente:
if($var) { //code } - La parentesi di apertura viene allineata alla riga di codice a cui fa riferimento, quella di chiusura va su una nuova linea:
if($var) { //code } - Le parentesi vengono allineate verticalmente ed indentate:
if($var) { //code }
Ne approfitto per segnalarti questa pagina di Wikipedia in cui puoi trovare molti stili di utilizzo delle parentesi graffe e la loro storia.
Variabili
Le variabili nel codice dovrebbero avere sempre un nome informativo, che faccia capire al volo a cosa servono o cosa contengono:
if($var == ‘pippo’) {
//my code
}
Da questo codice non si capisce a cosa realmente serva la variabile $var. Ok, sto facendo un controllo, ma di cosa? Un nome, un username, una password?
if($username == ‘pippo’) {
//my code
}
Decisamente meglio ora, non credi?
Attento però. Non abusare di questa regola, utilizzandola dove palesemente inutile: in un ciclo for, il contatore non ha bisogno di chiamarsi $contatoreDelMioCiclo, basta un semplice $i.
Scegli anche un metodo per nominare le variabili.
- CamelCase: capitalizzare l’iniziale di ogni parola;
- Caratteri minuscoli ed uso degli underscore ( _ ) per dividere le parole;
//Camel Case $esempioDiCamelCase; //Uso degli underscore $esempio_di_underscore;
Spazi bianchi
Utilizza gli spazi bianchi dove possono migliorare la leggibilità del codice.
Io personalmente li utilizzo:
- prima e dopo ogni parentesi;
- prima e dopo il carattere di unione ( . nel caso di PHP o ad esempio + nel caso di Javascript );
- dopo ogni virgola;
- prima e dopo ogni carattere matematico o di confronto
if( $var ) {
$array = array( ‘first_val’, ‘second_val’ );
echo ‘Spazio dopo il punto ’ . ‘ per aumentare la leggibilità’;
echo 2 + 3 - 4;
}
Gli spazi bianchi comprendono anche le linee vuote e i ritorni a capo.
È corretto lasciare una linea vuota dopo la dichiarazione di una condizione, di un ciclo o di una funzione e prima della rispettiva chiusura:
if( $var ) {
$array = array( ‘first_val’, ‘second_val’ );
echo ‘Spazio dopo il punto ’ . ‘ per aumentare la leggibilità’;
echo 2 + 3 - 4;
}
È meglio scrivere su più righe la dichiarazione di un array con più di un elemento o la dichiarazione di una funzione, istruzione condizionale o ciclo con più condizioni:
$array = array(
‘primo valore’,
‘secondo valore’
);
if( $my_first_var &&
$my_second_var &&
$my_third_var ) {
//code
}
Commenti
Non mi stancherò mai di ripeterlo, commenta il tuo codice, e fallo per due semplici motivi:
- Quando andrai a rileggerlo dopo qualche anno, in pochi minuti saprai cosa fa e come funziona;
- Altri programmatori che dovranno per un motivo o per un altro lavorare sul tuo codice non avranno problemi a comprenderlo.
Se devi modificare uno script scritto precedentemente, aggiorna anche i commenti relativi alle porzioni di codice modificate. Questo perché in futuro potresti trovarti a leggere informazioni errate e potresti fare modifiche che invece di migliorare il markup lo peggioreranno.
In ogni linguaggio esistono più stili per commentare il codice:
- Commenti su riga singola
- Commenti su più righe
Quando utilizzare l’uno o l’altro?
Il commento su riga singola va utilizzato per brevi annotazioni o descrizioni.
if( $is_valid_email ) {
//Controllo la correttezza del nome e del nome e del cognome
if( $is_valid_name_surname ) {
//Vari controlli
}
} //if( $is_valid_email)
Come noti dall’ultima riga di codice, è molto comodo utilizzare i commenti a riga singola anche in corrispondenza delle parentesi di chiusura, per indicare a quale istruzione essi appartengono.
I commenti a riga multipla invece andrebbero utilizzati all’inizio di ogni file per indicare cosa contiene, prima di ogni dichiarazione di classe o funzione per indicare i parametri che accetta, il tipo di valore restituito, la sua descrizione ecc…
function mia_funzione_anonima( $var ) {
return true;
}
/**
* Questa funzione non fa niente, ma è un ottimo esempio
* per mostrare i commenti a riga multipla.
*
* @param bool $var Un valore qualunque, che sia booleano.
* @return bool
*/
function mia_funzione_commentata( $var ) {
return true;
}
Per quanto mi riguarda utilizzo le linee guida di DocBlox per i commenti per due motivi:
- Sono estremamente esplicativi;
- Tramite quel software e i soli commenti, si può generare la documentazione del proprio codice.
Ricorda di commentare il codice man mano che lo scrivete: dopo sarà sicuramente troppo da commentare e inizierete a rimandare e rimandare e rimandare…
Ti segnalo infine gli standard di scrittura di WordPress che trovo essere delle ottime linee guida da seguire.
Conclusioni
Con questo articolo non voglio costringerti a cambiare il tuo stile di programmazione, ma aiutarti a capire che è meglio scrivere correttamente il proprio codice, anche se all’inizio può essere noioso stare attenti all’indentazione, ad un certo stile, ai commenti ecc. Del resto quando inizierai a scrivere progetti con script di molte pagine e numerose classi, ti accorgerai che diventa assolutamente necessario saper ottimizzare il markup nel modo più usabile possibile.
E poi diciamoci la verità, è una grande soddisfazione completare uno script e ammirare la sua bellezza con tutti i commenti che lo accompagnano, le parentesi tutte al loro posto, le variabili esplicative…come si suol dire in certi casi, “Code is poetry”, il codice è poesia, perciò tanto vale assicurarsi che la forma renda il più gradevole possibile la sostanza.
Sei d’accordo?
L'autore
Articoli correlati
Potresti essere interessato anche ai seguenti articoli:
18 commenti
Trackback e pingback
-
Articoli del mese Aprile 2012 | Saverio Gravagnola
[...] formattare e commentare il proprio codice? (Your Inspiration [...]
Grande Nicola,
possono sembrare cose banali, ma la stragrande maggioranza dei developers non le applica :)
Grazie Tiziano!
Purtroppo hai ragione, pochi rispettano queste poche regole… Mi è capitato più volte di scaricare codice ottimo ma che ho dovuto abbandonare perchè era impossibile metterci mano…
Ma che bravo questo ragazzo! :D
Lori così mi fai arrossire :D
Bell’articolo. Comunque abbasso il Camel_Case, ho dovuto pure metterci l’underscore, è talmente abusato negli sms e addirittura in qualche folgorato su twitter che mi provoca un senso di oppressione vederlo. Ola_Eli
Grazie Elisa! Personalmente io non faccio molta differenza tra il CC o gli underscore. Mi piacciono entrambi.
È solo questione di gusti ed abitudine.
ahahah! è vero :D sa troppo di bimbiminkia! :P
A me il CamelCase piace, per tanti motivi, mi da un senso di leggibilità più rapido. Per il resto, fortunatamente sono cose che già applico quindi sono salvo :D.
Grazie comunque del bell’articolo, è sempre un bene ricordare le nozioni di base che poi si applicano a tutto il mondo della programmazione e non solo al web
Buon per te Giuliano! E grazie!
CamelCase tutta la vita XD fa molto più OOP !! Scherzi a parte, penso che non ci sia nemmeno da discutere sull’importanza dei commenti e della corretta formattazione del proprio codice..Basti pensare di prendere in mano un progetto ‘vecchio’ di qualche mese e rimetterci mano…senza commenti. Suicidio. Per non parlare del codice altrui..autolesionismo puro.
Da discutere no, non c’è. Il problema è che in moltissimi nemmeno ci pensano a formattare il codice.
Penso che questa cosa debba essere insegnata ai programmatori fin dall’inizio. Quando andavo a scuola, ad esempio, non mi hanno mai insegnato a commentare o formattare. A stento ci hanno spiegato cosa fossero i commenti…
sono d’accordissimo sull’identazione (no ai soft-tab con gli spazi) e in generale sugli “standard” di formattazione che spesso cambiano da linguaggio a linguaggio.
non completamente sui commenti: un codice ben scritto, con metodi e funzioni ben dichiarate spesso si autodocumenta da se…ma comunque concordo sul fatto che i commenti siano un valore aggiunto.
filosofie come DRY o pattern di programmazione sono sconosciute ai più, lo dice uno che non è un coder puro 100% ma un “ibrido”…
purtroppo molti programmatori (e soprattutto in italia) sono quick ‘n’ dirty, qualcuno addirittura lo chiama lo “spaghetti-coding”.
ma per fortuna in posti come github non c’è spazio per il codice marcio, una cialtronata scritta in spaghetti-coding quando viene pushata, non viene nemmeno presa in considerazione dai mantainer delle repo =)
Lo spaghetti-code è uno dei peggior anti-pattern secondo me! Finchè si programma in singolo ci si POTREBBE anche passar sopra…
Ma se si è in un team non ci si può permettere di scrivere codice in quel modo…
Ottimo articolo! Non è una perdita di tempo, io ancor prima di scrivere il codice scrivo i commenti, è un modo anche per fare una analisi a runtime di quello che si sta scrivendo e mettere dei segnalibri ancor prima di codificare tutto.
Il Camel Case rientra nelle linee guide “della casa” se si lavora con linguaggi Microsoft e se si installano tools di refactoring. Ad esempio le classi si scrivono in maiuscolo (NomeClasse) e le variabili in minuscolo (nomeVariabile)…
Ci sono tante scuole di pensiero ma come hai detto l’importante è ordinare il codice e commentarlo.
E poi i nomi delle variabili… Pensa che la prima volta che son venuto a lavorare a Torino ho preso in mano un applicativo di un collaboratore e aveva scritto il codice in… piemontese! E letto da me, un pugliese, aveva davvero poco senso (ma tante risate :)
Ancora complimenti
Della serie “ho visto cose che voi umani non potete neanche immaginare” :)
Anche io faccio come te. Sempre prima i commenti! Anche perchè se non riesco a finire il codice, quando lo riprendo già so cosa e come deve funzionare una determinata pagina!
Molto utile. Qualcosina l’applicavo già, ma gli altri sono ottimi consigli per me che sono entrata da poco nel Php :)
Grazie!
Grazie Manuela! :)