2015-04-23 11 views

risposta

182

Il primo modulo è denominato Javadoc. Lo usi quando scrivi API formali per il tuo codice, che vengono generate dallo strumento javadoc. Per un esempio, the Java 7 API page utilizza Javadoc ed è stato generato da tale strumento.

Alcuni elementi comuni che ci si vede in Javadoc includono:

  • @param: questo è usato per indicare quali parametri vengono passati a un metodo, e quale valore stanno dovrebbe avere

  • @return: questo è usato per indicare quale risultato il metodo sta per restituire

  • @throws: questo è usato per indicare che un metodo genera un'eccezione o errore nel caso di certi input

  • @since: questo è usato per indicare la versione più antica Java questa classe o funzione era disponibile in

A titolo di esempio, ecco Javadoc per il metodo di Integercompare:

/** 
* Compares two {@code int} values numerically. 
* The value returned is identical to what would be returned by: 
* <pre> 
* Integer.valueOf(x).compareTo(Integer.valueOf(y)) 
* </pre> 
* 
* @param x the first {@code int} to compare 
* @param y the second {@code int} to compare 
* @return the value {@code 0} if {@code x == y}; 
*   a value less than {@code 0} if {@code x < y}; and 
*   a value greater than {@code 0} if {@code x > y} 
* @since 1.7 
*/ 
public static int compare(int x, int y) { 
    return (x < y) ? -1 : ((x == y) ? 0 : 1); 
} 

Il secondo modulo è un commento di blocco (su più righe). Si utilizza questo se si desidera avere più righe in un commento.

Dirò che vorresti usare solo il secondo modulo con parsimonia; cioè, non si vuole sovraccaricare il codice con commenti di blocco che non descrivono quali comportamenti si suppone che abbiano il metodo/la funzione complessa.

Poiché Javadoc è il più descrittivo dei due ed è possibile generare la documentazione effettiva come risultato dell'utilizzo, l'uso di Javadoc sarebbe preferibile ai commenti di blocco semplici.

+26

Un altro bel vantaggio di utilizzare Javadoc invece di semplici commenti di blocco è che quando si inserisce un commento Javadoc prima di un elemento Java (ad es. una firma di metodo, una dichiarazione di campo, una classe ecc.) ciò consente agli IDE - almeno Eclipse di sicuro - di mostrare il proprio commento (ad esempio in un suggerimento) quando si sposta il cursore - o si passa con il mouse - su un riferimento a quell'elemento Java. – SantiBailors

+0

Va bene usare i commenti di documenti java per le variabili? –

+0

@the_prole: È possibile, ma non vedo molto valore in esso a meno che non faccia parte di un pacchetto di tipo Costanti. Anche allora, i commenti in linea sono stati più preziosi nella mia esperienza. – Makoto

19

Il primo è un commento Javadoc. Possono essere elaborati dallo strumento javadoc per generare la documentazione dell'API per le classi. Il secondo è un commento di blocco normale.

-1

Java supporta due tipi di commenti:

  • /* multiline comment */: Il compilatore ignora tutto, dai /* a */. Il commento può estendersi su più righe.

  • // single line: Il compilatore ignora tutto da // fino alla fine della riga.

Alcune strumento come javadoc uso un commento speciale su più righe per il loro scopo. Ad esempio /** doc comment */ è un commento di documentazione utilizzato da javadoc durante la preparazione della documentazione generata automaticamente, ma per Java è un semplice commento multilinea.

+12

Il linguaggio Java supporta solo due tipi di commenti. Un commento sotto forma di '/ ** .. * /' è solo un normale commento multilinea, e il primo carattere al suo interno sembra essere un asterisco. –

3

Commenti in una lista di codice Java sono i personaggi in grigio:

/** 
* The HelloWorldApp class implements an application that 
* simply displays "Hello World!" to the standard output. 
*/ 
class HelloWorldApp { 
    public static void main(String[] args) { 
     System.out.println("Hello World!"); //Display the string. 
    } 
} 

Il linguaggio Java supporta tre tipi di commenti:

/* text */ 

Il compilatore ignora tutto, dai /* a */.

/** documentation */ 

Questo indica un commento di documentazione (doc commento, in breve). Il compilatore ignora questo tipo di commento, proprio come ignora i commenti che utilizzano /* e */. Lo strumento javadoc JDK utilizza i commenti del doc durante la preparazione della documentazione generata automaticamente.

// text 

Il compilatore ignora tutto da // fino alla fine della riga.

Ora per quanto riguarda quando si dovrebbe utilizzare loro:

Usa // text quando vuoi commentare una singola riga di codice.

Utilizzare /* text */ quando si desidera commentare più righe di codice.

Utilizzare /** documentation */ quando si desidera aggiungere alcune informazioni sul programma che può essere utilizzato per la generazione automatica della documentazione del programma.

3

Il primo è per Javadoc definito sopra le classi, le interfacce, i metodi ecc. È possibile utilizzare Javadoc come suggerisce il nome per documentare il codice su ciò che la classe fa o quale metodo fa e generare report su di esso.

Il secondo è il commento del blocco di codice. Ad esempio, si dispone di un blocco di codice che non si desidera che il compilatore interpreti, quindi si utilizza il commento del blocco di codice.

un altro è // questo si utilizza a livello di istruzione per specificare cosa devono fare le linee di comando dei codici.

Ci sono alcuni altri anche come // TODO, questo segnerà che si vuole fare qualcosa in seguito quel luogo

// FIXME si può usare quando si ha qualche soluzione temporanea, ma si desidera visitare più tardi e Rendilo migliore.

Spero che questo aiuti

119

Per il linguaggio di programmazione Java , non v'è alcuna differenza tra i due. Java ha due tipi di commenti: commenti tradizionali (/* ... */) e commenti di fine riga (// ...). Vedi lo Java Language Specification.Quindi, per il linguaggio di programmazione Java, sia /* ... */ sia /** ... */ sono istanze di commenti tradizionali, e sono entrambi trattati esattamente allo stesso modo dal compilatore Java, cioè vengono ignorati (o più correttamente: vengono trattati come spazi bianchi).

Tuttavia, come programmatore Java, non si utilizza solo un compilatore Java. Si utilizza un'intera catena di strumenti, che include per es. il compilatore, un IDE, un sistema di compilazione, ecc. E alcuni di questi strumenti interpretano le cose in modo diverso rispetto al compilatore Java. In particolare, i commenti /** ... */ vengono interpretati dallo strumento Javadoc, che è incluso nella piattaforma Java e genera documentazione. Lo strumento Javadoc eseguirà la scansione del file di origine Java e interpreterà le parti tra /** ... */ come documentazione.

Questo è simile al tag come FIXME e TODO: se si include un commento del tipo // TODO: fix this o // FIXME: do that, la maggior parte degli IDE metterà in evidenza tali commenti in modo che non si dimentica di loro. Ma per Java, sono solo commenti.

+39

+1 per fare l'importante distinzione che la sintassi Javadoc non fa parte della lingua, che nessun'altra risposta ha attualmente acquisito. –

+0

Questo è il motivo per cui si può avere un progetto che si compila bene in Maven ma non appena si decide di allegare JavaDocs inizia a lamentarsi perché lo strumento 'javadoc' non può interpretare qualcosa. –

13

Leggere la sezione 3.7 of JLS spiegare bene tutto ciò che è necessario sapere sui commenti in Java.

Ci sono due tipi di commenti:

  • /* testo */

Un commento tradizionale: tutto il testo dai caratteri ASCII/* per i caratteri ASCII */è ignorato (come in C e C++).

  • // testo

Un commento end-of-line: tutto il testo dai caratteri ASCII // alla fine della riga viene ignorato (come in C++).


tua domanda,

Il primo

/** 
* 
*/ 

consente di dichiarare Javadoc Technology.

Javadoc è uno strumento che analizza le dichiarazioni e documentazione commenti in un insieme di file di origine e produce una serie di pagine HTML che descrivono le classi, interfacce, costruttori, metodi e campi. È possibile utilizzare un doclet Javadoc per personalizzare l'output di Javadoc. Un doclet è un programma scritto con l'API Doclet che specifica il contenuto e il formato dell'output generato dallo strumento. È possibile scrivere un doclet per generare qualsiasi tipo di output di file di testo, ad esempio HTML, SGML, XML, RTF e MIF. Oracle fornisce un doclet standard per la generazione della documentazione dell'API in formato HTML . Doclet può anche essere utilizzato per eseguire attività speciali non correlate alla produzione di documentazione API.

Per ulteriori informazioni su Doclet fare riferimento allo API.

Il secondo, come spiegato chiaramente in JLS, ignorerà tutto il testo tra /* e */ quindi viene utilizzato per creare commenti multilinea.


Alcune altre cose che si potrebbe desiderare di sapere di commenti in Java

  • Commenti non fanno il nido.
  • /* and */ non ha alcun significato speciale nei commenti che iniziano con //.
  • // non ha alcun significato speciale nei commenti che iniziano con /* or /**.
  • La grammatica lessicale implica che i commenti non si verifichino all'interno di caratteri letterali (§3.10.4) o stringhe letterali (§3.10.5).

Così, il testo che segue è un singolo commento completo:

/* this comment /* // /** ends here: */ 
4

non credo che le risposte esistenti affrontati in maniera adeguata questa parte della domanda:

Quando devo usare loro?

Se si scrive un'API che sarà pubblicato o riutilizzati all'interno della vostra organizzazione, si dovrebbe scrivere commenti completi Javadoc per ogni public classe, metodo, e il campo, così come protected metodi e campi di non final classi. Javadoc dovrebbe coprire tutto ciò che non può essere trasmessa dalla firma del metodo, come precondizioni, postcondizioni, argomenti validi, le eccezioni di runtime, le chiamate interne, ecc

Se si scrive un'API interna (quella che viene utilizzato da diversi parti dello stesso programma), Javadoc è probabilmente meno importante. Ma a beneficio dei programmatori di manutenzione, dovresti comunque scrivere Javadoc per qualsiasi metodo o campo in cui l'uso o il significato corretti non sono immediatamente evidenti.

La "caratteristica killer" di Javadoc è che è strettamente integrata con Eclipse e altri IDE. Uno sviluppatore deve solo spostare il puntatore del mouse su un identificatore per imparare tutto ciò che è necessario sapere. Il riferimento costante alla documentazione diventa una seconda natura per sviluppatori Java esperti, che migliora la qualità del proprio codice. Se la tua API non è documentata con Javadoc, gli sviluppatori esperti non vorranno usarlo.

-1
  • singolo commento per esempio: // commento
  • multi linea commento per esempio:/* commento */
  • javadoc commento ad es:/** commento */
+2

Questo non aggiunge nulla rispetto alle risposte esistenti. – shmosel