- Redigere la documentazione di programma secondo diversi livelli di granularità
- Applicare le regole della sintassi dei linguaggi di programmazione
- Analizzare e documentare il codice per favorire la manutenibilità del software
I commenti sono porzioni di testo all'interno di un file sorgente che il compilatore ignora completamente. La loro funzione non è istruire la macchina, ma comunicare con gli esseri umani che leggeranno il codice.
In Java disponiamo di tre tipologie di commenti:
| Tipo | Sintassi | Utilizzo tipico |
|---|---|---|
| Singola riga | // testo |
Brevi spiegazioni di una riga di codice. |
| Multilinea | /* testo */ |
Descrizioni più lunghe o disattivazione di blocchi di codice. |
| Javadoc | /** testo */ |
Documentazione tecnica automatizzabile per classi e metodi. |
L'obiettivo di un buon programmatore è scrivere commenti che spieghino il perché di una scelta logica, piuttosto che limitarsi a descrivere cosa fa il codice (che dovrebbe essere già chiaro dal nome delle variabili).
LABORATORIO
Documentare un Software Gestionale
Impareremo a rendere leggibile e professionale un codice Java utilizzando correttamente la sintassi dei commenti.
- Browser web aggiornato
- IDE Online: OnlineGDB.com
1 Setup e Commento a riga singola
Aprite OnlineGDB e impostate il linguaggio su Java. Inserite il seguente codice e utilizzate i commenti a riga singola per descrivere le variabili.
public class Main {
public static void main(String[] args) {
double saldo = 500.0; // Saldo iniziale del conto corrente
double prelievo = 50.0; // Importo da prelevare
saldo = saldo - prelievo;
System.out.println("Nuovo saldo: " + saldo);
}
}
2 Commento Multilinea per l'intestazione
È buona norma inserire un'intestazione all'inizio di ogni file per indicare l'autore e lo scopo del progetto. Aggiungete in cima al file:
/* * Progetto: Gestione Conto Corrente
* Autore: Studente Classe 4
* Versione: 1.0
*/
3 Esercizio: Manutenzione Codice
Immaginate di dover "spegnere" temporaneamente una funzionalità senza cancellarla (debugging). Utilizzate il commento multilineare per disattivare la riga del calcolo del saldo e osservate come il programma ignora l'operazione durante l'esecuzione.
4 Javadoc
Javadoc è uno strumento ufficiale di Java che permette di generare automaticamente documentazione HTML a partire dai commenti nel codice.
- Sostituite il commento dell'intestazione con un blocco Javadoc (iniziando con
/**). - Aggiungete un commento a riga singola che spieghi il significato della variabile saldo dopo l'operazione di sottrazione.
- Verificate premendo Run che i commenti non influiscano sul risultato finale visualizzato in console.
La Sintassi Javadoc
Un commento Javadoc inizia sempre con /** (due asterischi) e finisce con */.
Al suo interno si usano dei tag speciali che iniziano con il simbolo @.
| Tag | Descrizione |
|---|---|
| @author | Indica chi ha scritto il codice. |
| @param | Spiega a cosa serve un parametro di input di un metodo. |
| @return | Spiega cosa restituisce il metodo come risultato. |
Esempio: Documentare una funzione di calcolo
Immaginiamo di scrivere un metodo che calcola l'IVA. Ecco come dovremmo documentarlo professionalmente:
/**
* Questa classe gestisce i calcoli fiscali aziendali.
* @author Prof.ssa Lucia Ponticelli
* @version 2.0
*/
public class CalcolatoreFiscale {
/**
* Calcola l'importo dell'IVA su un prezzo netto.
* @param prezzoNetto Il valore del prodotto senza tasse
* @param aliquota L'aliquota IVA da applicare (es. 22.0)
* @return Il valore dell'imposta calcolato
*/
public double calcolaIva(double prezzoNetto, double aliquota) {
return (prezzoNetto * aliquota) / 100;
}
}
Perché è utile?
Se passate il mouse sopra il nome del metodo in un IDE professionale (come IntelliJ o Eclipse), vedrete apparire un popup con la spiegazione che avete scritto. È come creare un "manuale d'istruzioni" integrato nel codice.
In sintesi
Argomenti: concetti principali, riepilogo, competenze
- I commenti sono porzioni di testo totalmente ignorate dal compilatore, dedicate esclusivamente ai programmatori.
- La sintassi di Java prevede tre varianti: commento a riga singola (
//), multilinea (/* ... */) e Javadoc (/** ... */). - I commenti efficaci descrivono le motivazioni architetturali (il <i>perché</i>) e non la pura semantica letterale dell\'istruzione (il <i>cosa</i>).
- I blocchi Javadoc utilizzano tag standardizzati con il simbolo
@per automatizzare l\'estrazione dei manuali tecnici in formato HTML.
- A documentare il codice sorgente rispettando i livelli di granularità richiesti dagli standard di sviluppo.
- L\'utilizzo operativo dei commenti multilinea come strumento di debugging per l\'isolamento di blocchi di codice fallimentari.
- La formattazione dei tag standard Javadoc (
@author,@param,@return) per la documentazione dei metodi di istanza. - L\'integrazione della documentazione inline per favorire la leggibilità e la manutenibilità a lungo termine del software.