5.2. Commenti di documentazione
Note: Vedi “Esempio di File Sorgente Java” per gli esempi dei formati di commento qui descritti.

Per ulteriori dettagli, vedi “How to Write Doc Comments for Javadoc” che include informazioni sui tag dei commenti di documentazione (@return, @param, @see):

    http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

Per altri dettagli sui doc comments e javadoc, visita l’home page di javadoc all’indirizzo:

    http://java.sun.com/products/jdk/javadoc/

I “doc comments” descrivono classi Java, interfacce, costruttori, metodi e campi. Ogni doc comment è compreso all’interno dei delimitatori di commento /**...*/, con un commento per ogni classe, interfaccia, o membro. Questo commento deve apparire solo prima della dichiarazione:

/**
 * La classe Esempio fornisce ...
 */
public class Esempio { ...

Notiamo che classi e interfacce ad alto livello non sono indentate, mentre lo sono i loro membri. La prima linea del commento di documentazione (/**) per classi e interfacce non è indentata; le linee di commento successive hanno ognuna 1 spazio di indentazione (per allineare verticalmente gli asterischi). I membri, inclusi i costruttori, hanno 4 spazi per la prima linea del doc comment e 5 spazi per quelli successivi.

Se si ha necessità di dare informazioni circa la classe, l’interfaccia, la variabile o il metodo, che non sono appropriate per la documentazione, usare un commento d’implementazione di blocco (vedi sezione 5.1.1) o a singola linea (vedi sezione 5.1.2) immediatamente dopo la dichiarazione. Per esempio, i dettagli sull’implementazione di una classe devono andare in un commento di blocco seguente l’istruzione class, non nel doc comment della classe.

I “doc comments” non devono essere posizionati dentro il blocco di definizione di un metodo o un costruttore, perché Java associa i commenti di documentazione con la pri ma dichiarazione dopo il commento.

6. Dichiarazioni

6.1. Numero per linea
Una dichiarazione per linea è raccomandata dal momento che incoraggia i commenit. In altre parole,

int livello; // livello di indentazione
int dimensione; // dimensione della tabella

è preferita rispetto a

int livello, dimensione;

Non mettere tipi differenti sulla stessa linea. Ad esempio:

int var,   vararray[]; //SBAGLIATO!

Nota: Gli esempi sopra usano uno spazio tra il tipo e l’identificatore. Un’altra alternativa accettabile è usare le tabulazioni, cioè:

int         livello;          // livello di indentazione
int         dimensione;       // dimenzione della tabella
Object      posizioneCorrente;// posizione della tabella attualmente selezionata

6.2. Inizializzazione
Provare ad inizializzare le variabili locali nel punto in cui sono dichiarate. L’unica ragione per non inizializzare una variabile dove è dichiarata, è se il suo valore iniziale dipende da un calcolo che prima occorre eseguire.

6.3. Posizione
Mettere le dichiarazioni all’inizio dei blocchi. (Un blocco è un codice racchiuso entro parentesi graffe “{” e “}”.) Non aspettare di dichiarare le variabili al loro primo uso; può confondere il programmatore inesperto e impedire la portabilità del codice dentro lo scope.

void mioMetodo() {
    int int1 = 0;       // inizio nel blocco del metodo

    if (condizione) {
        int int2 = 0;       // inizio del blocco "if"
        ...
    }
}

L’unica eccezione a questa regola sono gli indici dei cicli for, che in Java possono essere dichiarati nell’istruzione stessa:

for (int i = 0; i < maxCicli; i++) { ... }

Evitare dichiarazioni locali che nascondono dichiarazioni a più alto livello. Ad esempio, non dichiarare una variabile con lo stesso nome in un blocco interno:

int conta;
...
mioMetodo() {
    if (condizione) {
        int conta; // EVITARE!
        ...
    }
    ...
}

6.4. Dichiarazioni di Classe e Interfaccia
Quando si codificano classi e interfacce Java, si dovrebbero rispettare le seguenti regole di formattazione:
Non mettere spazi tra il nome del metodo e la parentesi “(“ che apre la lista dei parametri.
La parentesi graffa aperta “{” si trova alla fine della stessa linea dell’istruzione di dichiarazione.
La parentesi graffa chiusa “}” inizia una linea indentandosi per mapparsi con la corrispondente istruzione di apertura, eccetto il caso in cui c’è un’istruzione vuota, allora la “}” dovrebbe stare immediatamente dopo la “{“.

class Esempio extends Object {
    int ivar1;
    int ivar2;
   
    Esempio(int i, int j) {
        ivar1 = i;
        ivar2 = j;
    }

    int metodoVuoto() {}

    ...
}

I metodi sono separati da una linea bianca.

Torna all'indice Generale del corso di Specifiche Sun di Software Planet