Introduzione
Perché un programmatore dovrebbe interessarsi alla forma del codice scritto piuttosto che focalizzare totalmente la propria attenzione sul suo significato? La risposta è molto semplice: ciò che sembra evidente e chiaro oggi quando sviluppiamo un programma con buona probabilità non lo sarà quando dovremo riprendere il progetto per applicare delle modifiche.
Se lavoriamo in un team di programmatori la situazione si complica ancora di più: immaginate una squadra di 5 programmatori impiegato nello stesso progetto, ognuno con un proprio stile di programmazione, nessun tipo di commento all'interno del codice. Un inferno vero e proprio.
Ecco quindi che nasce la necessità per un programmatore di curare l'aspetto formale e la documentazione del proprio codice sia quando esso venga reso disponibile al pubblico (Es. uno script open source rilasciato sotto gpl) sia per progetti commerciali.
Ovviamente il Php non si discosta da questa necessità, quindi diamo un'occhiata a qualche spunto per rendere il proprio codice più comprensibile e facilmente gestibile.
I commenti: una risorsa o una scocciatura
Uno dei lavori più gravosi nello sviluppo di un progetto per un programmatore risiede nella stesura della documentazione di ciò che stiamo scrivendo. Anch'io preferirei scrivere 100 linee di codice piuttosto che una di commento ma mi rendo conto che questi si rendono necessari e permettono di risparmiare del tempo prezioso in futuro.
Iniziamo dalle basi: cosa sono i commenti? Non sono altro che parti inserite all'interno del codice che vengono ignorate completamente dai compilatori (nei linguaggi compilati o pseudo compilati come c, c++, java) o dagli interpreti (nei linguaggi interpretati come perl oppure il nostro php). Questo significa che all'interno di un commento possiamo inserire qualsiasi cosa.
Il Php supporta tre tipi di commenti: quelli precedeti dal simbolo cancelletto (#) in stile perl, quelli preceduti da doppio slash (//) in stile c e quelli posti tra slash e asterisco (/*) e asterisco e slash (*/).
<?php
# Commento in stile perl
// Commento in stile c
/* Commento multilinea in stile c++ */
?>
Le differenze tra questi tre tipi sono presto dette: i primi due sono equivalenti e rendono commento tutto ciò che si trova alla loro destra fino alla fine della linea, creano quindi commenti da una sola linea; il terzo tipo invece rende commento tutto ciò che si trova tra i caratteri di inizio (/*) e i caratteri di fine (*/) dando quindi la possibilità di creare commenti multilinea anche di una certa sostanza. Quest'ultima caratteristica li rende perfetti per spiegazioni di una certa lunghezza o per header corposi in cui inserire riferimenti all'autore o alla funzione dello script, ma può portare a problemi di incomprensione.
<?Php // Senza un editor con l'highlight per il codice Php
// probabilmente non ci accorgeremmo immediatamente
// dell'utilizzo della variabile $var6 nella seconda
// parte del codice
echo $var1 + $var2 + //$var3 + $var4 + $var5 + $var6 +
$var7;
echo $var1 + $var2 + /* $var3 + $var4 + $var5 + */ $var6 +
$var7;
?>
Quanto e cosa devo commentare?
Una volta compresa l'importanza del commento all'interno di codice di programmazione ci potremmo far trascinare e giungere all'estremo opposto: riempire di commenti ogni spazio libero da codice. È inutile dire che la sovrabbondanza di commenti è dannosa quanto l'assenza. A questo punto il programmatore si chiede quindi che cosa debba commentare e in che modo.
Non esistono delle regole universali, bisogna individuare le migliori caso per caso e applicarle correttamente.
$var = $a + $b; // sommo $a e $b
Un commento del genere ad esempio è assolutamente inutile, chi legge è già in grado di capire che quelle due variabili vengono sommate, mentre magari non è altrettanto chiaro il perché vengano sommate o il loro contenuto. Un commento del genere sarebbe stato sicuramente più utile:
$var = $a + $b; // Ricavo gli abitanti di Roma sommando quelli del comune e quelli della provincia
Qualche consiglio sul dove mettere commenti
- Un commento multilinea in testa allo script con indicazioni dello sviluppatore, ultima modifica, nome dello script, funzionalità, parametri provenienti dall'esterno attesi, indicazioni di copyright
- Appena dopo la dichiarazione di una funzione per descrivere i parametri attesi, il funzionamento della stessa, il significato del valore restituito (Ad esempio attraverso l'utilizzo di phpDocumentor)
- Nelle classi per descrivere le variabili interne
- In presenza di un grosso annidamento di parentesi graffe (molti if/else e cicli annidati) può tornare utile inserire come commento alla parentesi graffa di chiusura la linea di apertura (Esempio: } // if($a > 5) )
- All'interno di un algoritmo particolarmente complesso sarebbe bene illustrare i vari passaggi e chiarire i punti poco chiari (tenete sempre a mente che un mese dopo aver sviluppato quell'algoritmo probabilmente non ricorderete il significato di ogni passaggio e in caso di un'eventuale modifica altrimenti dovrete studiare da capo il vostro stesso codice)
Aggiornate i commenti!
Bene, ora avete la vostra applicazione ben commentata. Un giorno andate a modificare un algoritmo in uno script ma non aggiornate i commenti. Tre settimane dopo tornate a modificare quell'algoritmo, leggete i vostri commenti per ricordarvi velocemente il funzionamento, modificate e stranamente le modifiche non sono andate a buon fine. Perché? Semplicemente perché i commenti non erano al passo dell'applicazione. Dei commenti non aggiornati sono a volte più dannosi dell'assenza di commenti perché danno una sicurezza che in realtà non esiste.
I nomi: sigle o descrizioni?
Se avete letto gli esempi presenti precedentemente probabilmente vi sarete resi conto di quanto possa essere frustrante leggere del codice che presenti variabili dal nome incomprensibile ($var1, $var2, $a, $b, ecc.) che a priori potrebbero essere tutto e niente. Non sarebbe stato forse meglio disporre di variabili dal nome più significativo di $creditoTotale, $creditoParziale, $debitoTotale, $debitoParziale?
Le variabili più significative di un'applicazione dovrebbero sempre avere nomi comprensibili e che richiamino immediatamente il concetto a cui sono legate. Perché parlo di variabili "significative"? Semplicemente perché all'interno di uno script possiamo trovare anche variabili con valore puramente di ausilio (ad esempio l'indice di un ciclo for, oppure l'indice di un'array in cambiamento costante); è abbastanza inutile e dispendioso indicare queste variabili con nomi significativi. Prendiamo ad esempio il famoso ciclo for, si potrebbe benissimo utilizzare una variabile indice dal nome $indiceDelCicloPerArray
for( $indiceDelCicloPerArray = 0;
$indiceDelCicloPerArray < 20;
++$indiceDelCicloPerArray ){
ma l'utilizzo di un nome tanto descrittivo in questa situazione non porta alcun vantaggio in termini di informazioni date rispetto ad una variabile dal nome molto più semplice come $i
for( $i = 0; $i < 20; ++$i ){
Questo in parole povere significa ancora una volta che dovete dosare bene l'utilizzo di questa tecnica e non utilizzarla dove palesemente inutile se non dannosa.
Per questi nomi di variabile molto informativi potete fare riferimento a varie tecniche tra cui le più diffuse sono: $NomeVariabilePrimaLetteraMaiuscola, $nomi_divisi_da_underscore, $intNotazioneUngherese. Non ci sono grosse differenze visive tra l'utilizzo di una piuttosto che di un'altra, ma dovete tenere bene a mente che la coerenza è uno degli obiettivi principali per quanto riguarda la forma: in un determinato progetto scegliete la notazione che preferite e usate sempre quella dall'inizio alla fine, renderà più semplice l'orientamento all'interno del codice.
Convenzioni analoghe dovranno essere prese nel momento in cui sceglierete i nomi per le funzioni.
La forma del codice: chiarezza e precisione
Capita a volte di prendere del codice scritto da qualcun altro e non riuscire a comprendere niente a prima vista semplicemente perché manca un'indentazione coerente oppure perché il codice sempre soffocante da quanto è concentrato. Per rimediare in questi casi abbiamo tre strumenti:
- l'indentazione
- gli spazi
- le linee vuote
Indentare il codice significa scrivere il codice facendo in modo che le parti ad uno stesso livello logico si trovino allieneate verticalmente. Questo porta dei notevoli vantaggi specialmente in presenza di cicli o strutture if/else in quanto vengono rese immediatamente visibili ed evidenti. Essenzialmente si può indentare il codice in due maniere: con gli spazi o con la tabulazione. Impostate il vostro editor come meglio credete ed usate uno spostamento orizzontale visibile maggiore di uno spazio ma non eccessivo: personalmente mi trovo bene con 4 caratteri.
Potete usare gli spazi per dare respiro ad un codice particolarmente denso rendendo istruzioni complicate più leggibili, ma anche per allineare parti di codice. Ad esempio prendiamo parte di codice in cui abbiamo la valorizzazione di diverse variabili:
//Esempio errato
$nome = 'Mario';
$cognome = 'Rossi';
$indirizzo = 'Via della Repubblica, 5';
$telefono = '0123456789';
all'interno di uno script complesso questa piccola parte potrebbe aumentare la complessità percepita rendendo ancora più difficile comprenderne il significato.
//Esempio corretto
$nome = 'Mario';
$cognome = 'Rossi';
$indirizzo = 'Via della Repubblica, 5';
$telefono = '0123456789';
Infine potete utilizzare delle linee vuote per evidenziare o separare diverse strutture logiche (come ad esempio la zona di valorizzazione variabili, un ciclo, una struttura switch).
Non sto cercando di imporre il mio tipo di indentazione o di utilizzo di spazi, sentitevi liberi di trovare il miglior compromesso secondo voi tra forma leggibile del codice e processo di scrittura dello stesso. L'importante è sempre mantenere una linea di coerenza all'interno di uno stesso progetto.
<?php
// Questo codice non è indentato, non utilizza spazi
// nè linee vuote per separare strutture logiche
while($i<10){if($i%2){echo'bla bla';}elseif(($i%2)==0){$check=true;}}
// Questo codice è molto più leggibile del precedente
while( $i < 10 ){
if( $i % 2 ){
echo 'bla bla';
}
elseif( ($i % 2) == 0 ){
$check = true;
}
}
?>
