Risposte:
La prima forma si chiama Javadoc . Lo usi quando stai scrivendo API formali per il tuo codice, che sono generate dallo javadocstrumento. Ad esempio, la pagina API di Java 7 utilizza Javadoc ed è stata generata da quello strumento.
Alcuni elementi comuni che vedresti in Javadoc includono:
@param: viene utilizzato per indicare quali parametri vengono passati a un metodo e quale valore devono avere
@return: viene utilizzato per indicare quale risultato restituirà il metodo
@throws: viene utilizzato per indicare che un metodo genera un'eccezione o un errore in caso di determinati input
@since: viene utilizzato per indicare la prima versione di Java in cui questa classe o funzione era disponibile
Ad esempio, ecco Javadoc per il comparemetodo di Integer:
/**
* 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);
}
La seconda forma è un commento a blocchi (multilinea). Lo usi se vuoi avere più righe in un commento.
Dirò che vorresti usare solo quest'ultima forma con parsimonia ; cioè, non vuoi sovraccaricare il tuo codice con commenti di blocco che non descrivono quali comportamenti dovrebbe avere il metodo / funzione complessa.
Poiché Javadoc è il più descrittivo dei due e puoi generare la documentazione effettiva come risultato del suo utilizzo, l'uso di Javadoc sarebbe più preferibile ai semplici commenti di blocco.
Per il linguaggio di programmazione Java , non c'è differenza tra i due. Java ha due tipi di commenti: commenti tradizionali ( /* ... */) e commenti di fine riga ( // ...). Vedi le specifiche del linguaggio Java . Quindi, per il linguaggio di programmazione Java, entrambi /* ... */e /** ... */sono istanze di commenti tradizionali, ed entrambi sono trattati esattamente allo stesso modo dal compilatore Java, cioè sono ignorati (o più correttamente: sono trattati come spazi bianchi).
Tuttavia, come programmatore Java, non si utilizza solo un compilatore Java. Si utilizza un'intera catena di strumenti, che include ad esempio il compilatore, un IDE, un sistema di generazione, 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 sorgente Java e interpreterà le parti tra loro /** ... */come documentazione.
Questo è simile a tag come FIXMEe TODO: se includi un commento come // TODO: fix thiso // FIXME: do that, la maggior parte degli IDE evidenzierà tali commenti in modo da non dimenticartene. Ma per Java, sono solo commenti.
javadocstrumento non è in grado di interpretare qualcosa.
Leggendo la sezione 3.7 di JLS spieghi bene tutto ciò che devi sapere sui commenti in Java.
Esistono due tipi di commenti:
- /* testo */
Un commento tradizionale: tutto il testo dai caratteri ASCII / * ai caratteri ASCII * / viene ignorato (come in C e C ++).
- //testo
Un commento di fine riga: tutto il testo dai caratteri ASCII // alla fine della riga viene ignorato (come in C ++).
Sulla tua domanda,
Il primo
/**
*
*/
viene utilizzato per dichiarare la tecnologia Javadoc .
Javadoc è uno strumento che analizza le dichiarazioni e i commenti della documentazione in un set di file di origine e produce un set di pagine HTML che descrivono classi, interfacce, costruttori, metodi e campi. È possibile utilizzare un doclet Javadoc per personalizzare l'output Javadoc. Un doclet è un programma scritto con l'API Doclet che specifica il contenuto e il formato dell'output che deve essere generato dallo strumento. È possibile scrivere un doclet per generare qualsiasi tipo di output di file di testo, come HTML, SGML, XML, RTF e MIF. Oracle fornisce un doclet standard per la generazione di documentazione API in formato HTML. Le doclet possono anche essere utilizzate per eseguire attività speciali non correlate alla produzione di documentazione API.
Per ulteriori informazioni su Docletconsultare l' API .
Il secondo, come spiegato chiaramente in JLS, ignorerà tutto il testo tra /*e */quindi verrà utilizzato per creare commenti multilinea.
Alcune altre cose che potresti voler sapere sui commenti in Java
/* and */non ha alcun significato speciale nei commenti che iniziano con //.//non ha alcun significato speciale nei commenti che iniziano con /* or /**.Pertanto, il seguente testo è un singolo commento completo:
/* this comment /* // /** ends here: */Non credo che le risposte esistenti abbiano affrontato adeguatamente questa parte della domanda:
Quando dovrei usarli?
Se stai scrivendo un'API che verrà pubblicata o riutilizzata all'interno della tua organizzazione, dovresti scrivere commenti Javadoc completi per ogni publicclasse, metodo e campo, nonché protectedmetodi e campi di non finalclassi. Javadoc dovrebbe coprire tutto ciò che non può essere trasmesso dalla firma del metodo, come precondizioni, postcondizioni, argomenti validi, eccezioni di runtime, chiamate interne, ecc.
Se stai scrivendo un'API interna (utilizzata da diverse 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 passare il puntatore del mouse su un identificatore per apprendere tutto ciò che deve sapere al riguardo. Il costante riferimento alla documentazione diventa una seconda natura per gli sviluppatori Java esperti, che migliora la qualità del proprio codice. Se la tua API non è documentata con Javadoc, gli sviluppatori esperti non vorranno utilizzarla.
I commenti nel seguente elenco di codice Java sono i caratteri 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 da /*a */.
/** documentation */Questo indica un commento di documentazione (commento doc, in breve). Il compilatore ignora questo tipo di commento, proprio come ignora i commenti che usano /*e */. Lo strumento javadoc JDK utilizza i commenti doc durante la preparazione della documentazione generata automaticamente.
// textIl compilatore ignora tutto dalla //fine della riga.
Ora riguardo a quando dovresti usarli:
Utilizzare // textquando si desidera 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 possono essere utilizzate per la generazione automatica della documentazione del programma.
Il primo è per Javadoc che definisci in cima a classi, interfacce, metodi ecc. Puoi usare Javadoc come suggerisce il nome per documentare il tuo codice su ciò che fa la classe o su quale metodo ecc. E generare un rapporto su di esso.
Il secondo è il commento del blocco di codice. Supponiamo ad esempio di avere un blocco di codice che non si desidera interpretare dal compilatore, quindi utilizzare il commento del blocco di codice.
un altro è // questo che usi a livello di istruzione per specificare cosa dovrebbero fare le righe di codice procedenti.
Ce ne sono anche altri come // TODO, questo segnerà che vuoi fare qualcosa più tardi in quel posto
// FIXME è possibile utilizzare quando si dispone di una soluzione temporanea, ma si desidera visitare più tardi e renderlo migliore.
Spero che questo ti aiuti
Java supporta due tipi di commenti:
/* multiline comment */: Il compilatore ignora tutto da /*a */. Il commento può estendersi su più righe.
// single line: Il compilatore ignora tutto //fino alla fine della riga.
Alcuni strumenti come javadoc usano un commento multilinea speciale 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.
/** .. */è solo un normale commento multilinea e il primo personaggio al suo interno sembra essere un asterisco.