Il linguaggio Java mette a disposizione due modalità per inserire nel file sorgente del testo che verrà scartato dal compilatore e che serve quindi soltanto per chi legge il programma, scrivere questo tipo di testo ha tanti vantaggi tra cui: ricordarci come funziona il programma quando lo riguarderemo tra un po' di tempo e permettere ad altri programmatori di capire come funziona il nostro codice.
Un cosa per cui invece i commenti non servono: sostituire del codice scritto bene!
commenti singola linea
int lato; // FIXME: un commento
Questo tipo di commenti inizia con il simbolo // e termina
alla fine della linea.
commenti su più linee
/* scambio il contenuto di base e altezza */ t = base; base = altezza; altezza = t;
In questo caso il commento inizia con /* e termina
con */.
Contrassegni di uso comune
Capita spesso di dover marcare una parte di programma affinche ci si possa ricordare in futuro che dobbiamo sistemare qualcosa, per farlo si inseriscono dei nomi particolari all'interno di un commento, in futuro basta aprire il pannello "Tasks" di Eclipse per vedere cosa ci resta da sistemare.
- TODO
- segnala che dobbiamo svolgere un lavoro (una parte di programma da completare)
- FIXME
- la parte di codice che segue è errata, va sistemata
Javadoc
la piattaforma java ha un modo standard per scrivere commenti in modo che possa
essere prodotta documentazione in maniera automatica.
Questi commenti sono dei normali commenti multilinea ma iniziano con
/** e terminano al solito con */ e contengono al loro interno
degli speciali marcatori che iniziano con @, questi marcatori devono trovarsi
all'inizio di una linea (possono essere preceduti da spazi bianchi e eventualmente da un asterisco).
I commenti javadoc non possono essere messi ovunque, possono comparire prima di: dichiarazioni di classi, metodi o campi (variabili al livello di classe).
Classi
Prima della dichiarazione di una classe può essere inserito un commento per indicare (tra le altre cose) cosa fa la classe stessa e chi l'ha scritta.
/**
* Questa classe somma il contenuto di due numeri inseriti dall'utente
* @author Pluto
*/
public class Sommatore extends Application {
Metodi
Nel caso dei metodi (o funzioni) possiamo ad esempio descrivere i parametri e cosa la funzione ritorna (calcola).
/**
* Calcola l'area del rettangolo
* @param base la misura della base del rettangolo
* @param altezza la misura dell'altezza del rettangolo
* @return la mosura dell'area
*/
public int area(int base, int altezza) {