Was ist der Unterschied zwischen
/**
* comment
*
*
*/
und
/*
*
* comment
*
*/
in Java? Wann sollte ich sie verwenden?
Die erste Form heißt Javadoc. Sie verwenden diese Form, wenn Sie formale APIs für Ihren Code schreiben, die von dem Tool javadoc
generiert werden. Ein Beispiel: [die Java 7 API-Seite] (http://docs.oracle.com/javase/7/docs/api/) verwendet Javadoc und wurde mit diesem Tool erstellt.
Einige übliche Elemente, die Sie in Javadoc sehen können, sind:
@param
: Dies wird verwendet, um anzugeben, welche Parameter an eine Methode übergeben werden und welchen Wert sie haben sollen.
@return
: Hier wird angegeben, welches Ergebnis die Methode zurückgeben wird
@throws": wird verwendet, um anzugeben, dass eine Methode bei bestimmten Eingaben eine Ausnahme oder einen Fehler auslöst
@since
: Hier wird die früheste Java-Version angegeben, in der diese Klasse oder Funktion verfügbar war.
Als Beispiel, hier's Javadoc für die compare
Methode 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 (mehrzeiliger) Blockkommentar. Sie verwenden diesen, wenn Sie mehrere Zeilen in einem Kommentar haben wollen.
Ich würde sagen, dass Sie die letztere Form nur sparsam verwenden sollten; das heißt, Sie wollen Ihren Code nicht mit Blockkommentaren überfrachten, die nicht beschreiben, welches Verhalten die Methode/komplexe Funktion haben soll.
Da Javadoc die beschreibendere der beiden Formen ist und Sie durch die Verwendung von Javadoc eine echte Dokumentation erstellen können, ist die Verwendung von Javadoc den einfachen Blockkommentaren vorzuziehen.
Java unterstützt zwei Arten von Kommentaren:
/* mehrzeiliger Kommentar */
: Der Compiler ignoriert alles von /*
bis */
. Der Kommentar kann sich über mehrere Zeilen erstrecken.
// einzeilig
: Der Compiler ignoriert alles von //
bis zum Ende der Zeile.
Einige Werkzeuge wie javadoc verwenden einen speziellen mehrzeiligen Kommentar für ihren Zweck. Zum Beispiel /** doc comment */
ist ein Dokumentationskommentar, der von javadoc verwendet wird, wenn es die automatisch generierte Dokumentation vorbereitet, aber für Java ist es ein einfacher mehrzeiliger Kommentar.