commenti

come documentare i programmi direttamente nel file sorgente

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 ad 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) {
da completare con altri tag