Antworten:
Die erste Form heißt Javadoc . Sie verwenden dies, wenn Sie formale APIs für Ihren Code schreiben, die vom javadocTool generiert werden . Zum Beispiel die Java 7 API-Seite Javadoc und wurde von diesem Tool generiert.
Einige allgemeine Elemente, die Sie in Javadoc sehen würden, sind:
@param: Hiermit wird angegeben, welche Parameter an eine Methode übergeben werden und welchen Wert sie voraussichtlich haben
@return: Dies wird verwendet, um anzugeben, welches Ergebnis die Methode zurückgeben wird
@throws: Dies wird verwendet, um anzuzeigen, dass eine Methode bei bestimmten Eingaben eine Ausnahme oder einen Fehler auslöst
@since: Dies wird verwendet, um die früheste Java-Version anzugeben, in der diese Klasse oder Funktion verfügbar war
Als Beispiel hier Javadoc für die compareMethode von 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);
}Die zweite Form ist ein Blockkommentar (mehrzeilig). Sie verwenden dies, wenn Sie mehrere Zeilen in einem Kommentar haben möchten.
Ich werde sagen, dass Sie die letztere Form nur sparsam verwenden möchten ; Das heißt, Sie möchten Ihren Code nicht mit Blockkommentaren überlasten, die nicht beschreiben, welches Verhalten die Methode / komplexe Funktion haben soll.
Da Javadoc die aussagekräftigere der beiden ist und Sie als Ergebnis der Verwendung eine tatsächliche Dokumentation erstellen können, ist die Verwendung von Javadoc einfachen Blockkommentaren vorzuziehen.
Für die Programmiersprache Java gibt es keinen Unterschied zwischen den beiden. Java hat zwei Arten von Kommentaren: traditionelle Kommentare ( /* ... */) und Zeilenende-Kommentare ( // ...). Siehe die Java-Sprachspezifikation . Also, für die Java - Programmiersprache, die beide /* ... */und /** ... */Instanzen der traditionellen Kommentare sind, und sie sind beide behandelt genau das gleiche durch den Java - Compiler, das heißt, sie werden ignoriert (oder richtiger: sie werden als Leerraum behandelt).
Als Java-Programmierer verwenden Sie jedoch nicht nur einen Java-Compiler. Sie verwenden eine gesamte Toolkette, die z. B. den Compiler, eine IDE, ein Build-System usw. enthält. Einige dieser Tools interpretieren die Dinge anders als der Java-Compiler. Insbesondere werden /** ... */Kommentare vom Javadoc-Tool interpretiert, das in der Java- Plattform enthalten ist und Dokumentation generiert. Das Javadoc-Tool scannt die Java-Quelldatei und interpretiert die Teile dazwischen /** ... */als Dokumentation.
Dies ähnelt Tags wie FIXMEund TODO: Wenn Sie einen Kommentar wie // TODO: fix thisoder // FIXME: do thateinfügen, markieren die meisten IDEs solche Kommentare, damit Sie sie nicht vergessen. Für Java sind dies jedoch nur Kommentare.
javadocTool etwas nicht interpretieren kann.
Lesen Sie in Abschnitt 3.7 von JLS alles, was Sie über Kommentare in Java wissen müssen.
Es gibt zwei Arten von Kommentaren:
- / * text * /
Ein traditioneller Kommentar: Der gesamte Text von den ASCII-Zeichen / * bis zu den ASCII-Zeichen * / wird ignoriert (wie in C und C ++).
- //Text
Ein Zeilenende-Kommentar: Der gesamte Text von den ASCII-Zeichen // bis zum Zeilenende wird ignoriert (wie in C ++).
Über Ihre Frage,
Der erste
/**
*
*/wird verwendet, um Javadoc Technology zu deklarieren .
Javadoc ist ein Tool, das die Deklarationen und Dokumentationskommentare in einer Reihe von Quelldateien analysiert und eine Reihe von HTML-Seiten erstellt, die die Klassen, Schnittstellen, Konstruktoren, Methoden und Felder beschreiben. Sie können ein Javadoc-Doclet verwenden, um die Javadoc-Ausgabe anzupassen. Ein Doclet ist ein Programm, das mit der Doclet-API geschrieben wurde und den Inhalt und das Format der Ausgabe angibt, die vom Tool generiert werden soll. Sie können ein Doclet schreiben, um jede Art von Textdateiausgabe zu generieren, z. B. HTML, SGML, XML, RTF und MIF. Oracle bietet ein Standard-Doclet zum Generieren von API-Dokumentation im HTML-Format. Doclets können auch verwendet werden, um spezielle Aufgaben auszuführen, die nicht mit der Erstellung der API-Dokumentation zusammenhängen.
Weitere Informationen finden Sie Docletin der API .
Der zweite, wie in JLS klar erläutert, ignoriert den gesamten Text dazwischen /*und */wird daher zum Erstellen mehrzeiliger Kommentare verwendet.
Einige andere Dinge, die Sie über Kommentare in Java wissen möchten
/* and */haben keine besondere Bedeutung in Kommentaren, die mit beginnen //.//hat keine besondere Bedeutung in Kommentaren, die mit beginnen /* or /**.Somit ist der folgende Text ein einzelner vollständiger Kommentar:
/* this comment /* // /** ends here: */Ich denke, die vorhandenen Antworten haben diesen Teil der Frage nicht angemessen angesprochen:
Wann soll ich sie verwenden?
Wenn Sie eine API schreiben, die in Ihrer Organisation veröffentlicht oder wiederverwendet wird, sollten Sie umfassende Javadoc-Kommentare für jede publicKlasse, Methode und jedes Feld sowie für protectedMethoden und Felder von Nichtklassen schreiben final. Javadoc sollte alles abdecken, was von der Methodensignatur nicht übermittelt werden kann, z. B. Vorbedingungen, Nachbedingungen, gültige Argumente, Laufzeitausnahmen, interne Aufrufe usw.
Wenn Sie eine interne API schreiben (eine, die von verschiedenen Teilen desselben Programms verwendet wird), ist Javadoc wohl weniger wichtig. Zum Nutzen der Wartungsprogrammierer sollten Sie Javadoc dennoch für alle Methoden oder Felder schreiben, bei denen die korrekte Verwendung oder Bedeutung nicht sofort ersichtlich ist.
Das "Killer-Feature" von Javadoc ist, dass es eng in Eclipse und andere IDEs integriert ist. Ein Entwickler muss nur den Mauszeiger über eine Kennung bewegen, um alles zu erfahren, was er darüber wissen muss. Das ständige Verweisen auf die Dokumentation wird für erfahrene Java-Entwickler zur zweiten Natur, was die Qualität ihres eigenen Codes verbessert. Wenn Ihre API nicht mit Javadoc dokumentiert ist, möchten erfahrene Entwickler sie nicht verwenden.
Kommentare in der folgenden Liste von Java-Code sind die ausgegrauten Zeichen:
/**
* 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.
}
}Die Java-Sprache unterstützt drei Arten von Kommentaren:
/* text */Der Compiler ignoriert alles von /*bis */.
/** documentation */Dies weist auf einen Dokumentationskommentar hin (kurz Dokumentkommentar). Der Compiler ignoriert diese Art von Kommentaren genauso wie Kommentare, die /*und verwenden */. Das JDK-Javadoc-Tool verwendet Dokumentkommentare, wenn automatisch generierte Dokumentationen erstellt werden.
// textDer Compiler ignoriert alles //bis zum Ende der Zeile.
Nun darüber, wann Sie sie verwenden sollten:
Verwenden // textSie diese Option, wenn Sie eine einzelne Codezeile kommentieren möchten.
Verwenden /* text */Sie diese Option, wenn Sie mehrere Codezeilen kommentieren möchten.
Verwenden /** documentation */ Sie diese Option, wenn Sie Informationen zum Programm hinzufügen möchten, die zur automatischen Generierung der Programmdokumentation verwendet werden können.
Das erste ist für Javadoc, das Sie oben in Klassen, Schnittstellen, Methoden usw. definieren. Sie können Javadoc als Namensvorschlag verwenden, um Ihren Code darüber zu dokumentieren, was die Klasse oder welche Methode usw. tut, und einen Bericht darüber zu erstellen.
Der zweite ist der Codeblockkommentar. Angenommen, Sie haben einen Codeblock, den der Compiler nicht interpretieren soll, dann verwenden Sie einen Codeblockkommentar.
Eine andere ist // dies, die Sie auf Anweisungsebene verwenden, um anzugeben, was die fortlaufenden Codezeilen tun sollen.
Es gibt auch andere wie // TODO. Dies markiert, dass Sie später an diesem Ort etwas tun möchten
// FIXME können Sie verwenden, wenn Sie eine temporäre Lösung haben, diese aber später besuchen und verbessern möchten.
Hoffe das hilft
Java unterstützt zwei Arten von Kommentaren:
/* multiline comment */: Der Compiler ignoriert alles von /*bis */. Der Kommentar kann sich über mehrere Zeilen erstrecken.
// single line: Der Compiler ignoriert alles //bis zum Ende der Zeile.
Einige Tools wie Javadoc verwenden für ihren Zweck einen speziellen mehrzeiligen Kommentar. Beispielsweise /** doc comment */handelt es sich um einen Dokumentationskommentar, der von javadoc bei der Erstellung der automatisch generierten Dokumentation verwendet wird. Bei Java handelt es sich jedoch um einen einfachen mehrzeiligen Kommentar.
/** .. */ist nur ein regulärer mehrzeiliger Kommentar, und das erste Zeichen darin ist zufällig ein Sternchen.