Nessun risultato. Prova con un altro termine.
Guide
Notizie
Software
Tutorial

Scrivere codice con stile

Consigli e suggerimenti per creare codice chiaro e leggibile
Consigli e suggerimenti per creare codice chiaro e leggibile
Link copiato negli appunti

Al contrario di quanto si possa comunemente pensare, un programma ben sviluppato non è solo quel software che funziona esattamente come avremmo voluto. Un programma ben scritto è anche quello che permette un rapido intervento sul codice sorgente e che consente a chiunque conosca il linguaggio di poter familiarizzare più o meno velocemente con la sua struttura senza dover passare tempo inutile a cercare di interpretare cosa il programmatore che l'ha creato volesse intendere con quell'istruzione.

È quindi importante curare non solo la parte visiva, ovvero l'interfaccia utente, ma anche il così detto back end, ovvero la parte nascosta, il codice sorgente. Le motivazioni sono abbastanza ovvie ma spesso non così sufficienti da indurre chi crea un codice a rispettare le norme base e le convenzioni stabilite.

Scrivere un codice corretto e pulito ci permetterà in qualsiasi momento di poter intervenire agevolmente su quanto creato. Se poi lavoriamo in un team di sviluppo o prevediamo che il sorgente possa essere letto da altre persone, a maggior ragione, lo stile con cui realizziamo il software sarà fondamentale per permettere a chiunque di comprenderlo.

Siccome è bene non sottovalutare questo aspetto vediamo alcune tra le principali convenzioni ed abitudini per programmare , nello specifico per scrivere un codice ASP. Molte di queste metodologie possono essere applicate sviluppando con altri linguaggi anche se spesso ciascuna risorsa presenta usi e consuetudini specifiche.

I commenti

La base di un codice ben scritto sono proprio i commenti, che non possono mancare in un qualsiasi programma. Allegare alle parti più significative di un programma una documentazione esplicativa è una buona abitudine troppo spesso dimenticata, anche da chi vi sta scrivendo.

Tuttavia, documentare anche solo con qualche riga un costrutto di istruzioni permetterà a voi di comprendere al volo il comportamento di quello che avevate prodotto nel caso vi troviate nella situazione di modificarlo. Se avete scritto un programma corretto è probabile che non tornerete a modificarlo fino a quando non sarà necessario aggiornarlo. Questa fase potrebbe avvenire dopo diversi anni rispetto a quando il codice è stato scritto e sicuramente un commento vi sarà di grande aiuto.

Un commento non è altro che una particolare informazione che verrà ignorata in fase di esecuzione dal webserver . È quindi possibile memorizzare un qualsiasi contenuto certi che non verrà eseguito. In ASP, al contrario di altri linguaggi, è presente solo il commento su riga singola e, nonostante questa limitazione sia parzialmente scomoda, è bene non prenderla come giustificazione.

Per inserire un commento in ASP è sufficiente far precedere le informazioni da un apice singolo ( ' ) ed il webserver passerà automaticamente alla prima istruzione successiva valida.

<%
' questo è un commento in ASP.
%>

Per scrivere un commento su più righe è necessario far precedere ciascuna riga da un apice:

<%
' questo è un commento in ASP
' che si sviluppa su 2 righe
%>

Quando, cosa e dove commentare?

Di norma è abitudine commentare un blocco di istruzioni particolarmente significativo. Ad esempio, nel caso un costrutto apra una connessione al database ed esegua una query per richiamare una serie di dati, potrebbe essere opportuno spiegarlo:

<%

' Esegui una query al database e preleva
' tutti i record che corrispondono all'ID
' passato nel campo cat= in querystring.
' La querystring viene fltrata.

intCatId = Request.Querystring("cat")
intCatId = filterId(intCatId)
strSQL = "SELECT * FROM nometabella WHERE ID = " & intCatId
...

%>

Altra istruzione dove è quasi un obbligo inserire un commento esplicativo sono le funzioni e le procedure. Scrivere una function di una ventina di righe senza documentare cosa venga eseguito è assai controproducente. Spesso, in linguaggi di programmazione dove classi e metodi sono la base, si usa documentare ampiamente la funzione , inserendo anche informazioni sui parametri richiesti ed i dati restituiti, oltre ad eventuali identificativi di versione.

Siccome ASP non ha le stesse esigenze di Java o C++, potrebbe essere sufficiente limitarsi ad una struttura come nell'esempio seguente, corrispondente ad una semplice funzione per filtrare degli ID numerici:

<%

' == Filtra ID ==
' Controlla e filtra l'input passato come parametro
' verificando che sia un formato ID valido.
' Se il formato è valido converte il dato
' in alternativa restituisce un valore convenzionale.
'
' @return l'ID filtrato se il formato è valido,
' 0 altrimenti.

public function filterId(input)

if IsNumeric(input) AND Len(Trim(input)) > 0 then
filterId = Cint(input)
else
filterId = 0
end if

end function

%>

Nella parte iniziale viene descritto il comportamento della funzione. In questo caso è poi stato preso in prestito l' indicatore @return che è comunemente usato in diversi linguaggi per definire il valore di ritorno della funzione. Altri dati possono essere inseriti a piacimento nel caso si desideri fornire maggiore documentazione.

Se si sta creando un programma mediamente grande con diversi include e librerie, è bene fornire anche un breve commendo ad inizio del file che descriva il compito di quell'include o delle informazioni contenuti all'interno.

Altra buona abitudine è inserire un commento in fase di dichiarazione di ciascuna variabile portante di un metodo. Consentirà di individuare velocemente quali sono le variabili da modificare in base al risultato che si desidera ottenere:

Dim strCategoria ' nome della categoria
Dim intCategoria ' ID della categoria
Dim blnVisibile ' impostare a true per pubblicare la categoria

Importante non esagerare

Se da una parte i commenti sono fondamentali, è importante non abusarne poiché si produrrebbe l'effetto opposto. Commentare ciascuna istruzione di un programma rende il codice eccessivamente pesante e abbastanza fastidioso da leggere:

<%

' inizio funzione
public function filterId(input)

' controlla se input è un numero e se non è vuoto
if IsNumeric(input) AND Len(Trim(input)) > 0 then
' restituisce input in intero
filterId = Cint(input)
' input non corrisponde ai parametri richiesti
else
' restituire un valore 0 convenzionale
filterId = 0
' fine controllo
end if

' fine funzione
end function

%>

Come è facile notare l'esempio appena esposto è notevolmente più "pasticciato" rispetto allo stesso illustrato in precedenza.

Per esperienza personale ritengo poi necessario fare un appunto a come scrivere un commento. Sebbene sia possibile usare qualsiasi simbolo grafico si voglia è buona norma non esagerare. Se a prima vista creare splendide cornici contenenti un commento risulta estremamente coreografico, il tempo speso per mantenere questa struttura potrebbe distoglierci dal nostro reale intento oppure aumentare la probabilità che la documentazione non venga aggiornata proprio per non cambiare questa grafica che con tanta abilità abbiamo realizzato.

Sì all'uso di qualche semplice separatore che possa aiutare la lettura, no alle coreografie per un commento.

I nomi di variabili ed istruzioni

Altro dilemma amletico, che spesso non trova risposte coerenti anche tra gli stessi programmatori, è quali nomi usare per variabili, funzioni e procedure. In linea generica è sufficiente applicare un semplice schema: il nome deve essere sufficiente esplicativo per la funzione che la variabile assume in un dato contesto .

In parole povere, se stiamo lavorando con variabili che dovranno memorizzare dati ed informazioni, non facciamo economia di lettere. Scrivere:

intSomma = Request.Form("somma")
Dim intScontoTotale, intScontoProdotto

è sicuramente più opportuno di:

s = Request.Form("x")
Dim st, sp

Allo stesso modo, nel caso stiamo costruendo un costrutto iterativo come un for, usare

for ii = 0 to 12
' istruzione
next

è sicuramente da preferire rispetto all'uso di un nome articolato e complesso.

Come anticipato in precedenza, è bene affidarsi alla ragione. Nonostante si tratti anche qui di un ciclo, nel caso di un While potrebbe essere opportuno adottare nuovamente una variabile coerente con lo scopo:

Do while blnArchivioVuoto = false
' istruzione
loop

Per quanto riguarda funzioni e procedure valgono le stesse regole prima esposte, aggiungendo che mai come in questo caso è fondamentale la chiarezza . È buona norma creare il nome di una funzione componendo il sostantivo dell'oggetto che la funzione andrà a modificare con un verbo che definisca l'azione:

filtraForm()
filtraQuerystring()
leggiCodiceProdotto()

sono sicuramente nomi da preferire rispetto a

form()
querystring()
prod()

I prefissi

È convenzione diffusa tra i programmatori ASP adottare la notazione Ungherese per creare un nome di una variabile. In poche parole, è buona norma far precedere ciascuna variabile da un prefisso che specifichi il tipo di dato che la variabile sarà destinata a conservare per tutta la durata dell'istruzione o, più comunemente, della pagina.

I vantaggi derivanti da questa convenzione sono diversi. In primo luogo, data una variabile in un qualsiasi punto del codice, permette di identificare immediatamente come trattare i dati che essa contiene. In secondo luogo consente di utilizzare più sostantivi per dati differenti ma che fanno riferimento allo stesso oggetto:

Dim strCategoria
Dim intCategoria

In questo caso è possibile usare il sostantivo categoria sia per creare una variabile che contenga ad esempio il nome della categoria, sia per una variabile destinata ad accogliere un ID numerico della categoria stessa. Sebbene in questo esempio l'uso sia banale, in codici strutturati può rivelarsi fondamentale, in particolare nel caso non si faccia uso di funzioni o procedure.

È possibile consultare un elenco dei prefissi standard adottati visitando la documentazione Microsoft.

Anche per le funzioni esistono dei prefissi convenzionali, in inglese, per determinate azioni. Ecco i principali:

  • is ¯ Usato per controlli booleani. Ex. isLogged()
  • has ¯ Usato per controlli di proprietà. Ex. hasChild()
  • get ¯ Usato per ottenere dei dati. Ex. getUserBrowser()
  • set ¯ Usato per impostare dei dati. Ex. setNewsTitle()

Spazi, indentazione e stesura del codice

Come per un tema, una lettera o una presentazione, anche per il codice è importante seguire alcune fondamentali norme stilistiche per aiutare la lettura e l'interpretazione. Siccome si tratta di semplici abitudini, vediamole in elenco.

Inserire una riga vuota al termine di ogni blocco di istruzione significativo

Separare ad esempio un ciclo dalle istruzioni successiva o un blocco per la lettura di un record dal successivo invio di email.

Indentare di un livello (spesso 1 tab) per ogni istruzione annidata

if (st rSomma > 0) then
Response.Write("Puoi comprare")
else
Response.Write("Non hai soldi nella carta")
end if

Inserire uno spazio dopo ogni istruzione condizionale e tra gli operatori

if (st rSomma > 0) then
' qualcosa
end if

al posto di

if(st rSomma>0)then
'qualcosa
end if

Sebbene il webserver sia in grado di comprendere ugualmente le istruzioni, potrebbe essere molto difficile modificare il codice in un programma che non consente la colorazione della sintassi.

Separate le istruzioni

Dim variabile
Dim altravariabile

variabile = 3

È sicuramente più chiaro di

Dim variabile, altravariabile : variabile = 3

Alcune considerazioni conclusive

Un fattore importante da comprendere è che quanto trattato sopra non rappresenta condizione obbligatoria per lo sviluppo di un programma, ma l'adozione di queste ed altre piccole abitudini può fare la differenza soprattutto nella revisione e nella diffusione di un programma.

È probabile che, dopo la lettura di questo articolo, molti di voi riconoscano nei propri codici diverse cose da aggiornare. Non lasciatevi però prendere dalla foga di rivoluzionare i vostri programmi poiché sarebbe una operazione eccessiva. Impegnatevi piuttosto a seguire questi ed altri piccoli accorgimenti nel futuro.

Infine, è bene essere al corrente che quanto espresso sopra non è legge ma sono abitudini maturate nel tempo grazie alla crescita professionale e culturale dei programmatori.

È quindi buona norma seguire queste abitudini e, perché no, dare una lettura ogni tanto a qualche codice ben scritto per trarne spunti validi.


Ti consigliamo anche