it-swarm.com.de

/ ** und / * in Java Kommentaren

Was ist der Unterschied zwischen

/**
 * comment
 *
 *
 */

und

/*
 * 
 * comment
 *
 */

in Java? Wann sollte ich sie benutzen?

175
dev ツ

Die erste Form heißt Javadoc . Sie verwenden dies, wenn Sie formale APIs für Ihren Code schreiben, die vom Tool javadoc generiert werden. Beispiel: die API-Seite Java 7 verwendet Javadoc und wurde von diesem Tool generiert.

Einige allgemeine Elemente, die Sie in Javadoc sehen würden, umfassen:

  • @param: Hiermit wird angegeben, welche Parameter an eine Methode übergeben werden und welchen Wert sie voraussichtlich haben

  • @return: Hiermit wird angegeben, welches Ergebnis die Methode zurückgeben wird

  • @throws: Gibt an, dass eine Methode bei bestimmten Eingaben eine Ausnahme oder einen Fehler auslöst

  • @since: Hiermit wird die früheste Java Version angegeben, in der diese Klasse oder Funktion verfügbar war

Hier ist Javadoc als Beispiel 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 Kommentar. 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 generieren können, ist die Verwendung von Javadoc einfachen Blockkommentaren vorzuziehen.

233
Makoto

Für die Programmiersprache Java gibt es keinen Unterschied zwischen den beiden. Java verfügt über zwei Arten von Kommentaren: herkömmliche Kommentare (/* ... */) und Zeilenende-Kommentare (// ...). Siehe Java Language Specification . Für die Programmiersprache Java sind also sowohl /* ... */ als auch /** ... */ Instanzen traditioneller Kommentare, und beide werden vom Compiler Java genau gleich behandelt, dh sie werden ignoriert (oder richtiger: sie werden als Leerzeichen behandelt).

Als Java - Programmierer verwenden Sie jedoch nicht nur einen Java - Compiler. Sie verwenden eine gesamte Werkzeugkette, die z. Der Compiler, eine IDE, ein Build-System usw. Einige dieser Tools interpretieren die Dinge anders als der Compiler Java. Insbesondere werden /** ... */ -Kommentare vom Javadoc-Tool interpretiert, das auf der Plattform Java enthalten ist und Dokumentation generiert. Das Javadoc-Tool durchsucht die Quelldatei Java und interpretiert die Teile zwischen /** ... */ als Dokumentation.

Dies ähnelt Tags wie FIXME und TODO: Wenn Sie einen Kommentar wie // TODO: fix this oder // FIXME: do that einfügen, markieren die meisten IDEs solche Kommentare, damit Sie nichts vergessen Sie. Bei Java handelt es sich jedoch nur um Kommentare.

134
Hoopje

Der erste ist Javadoc Kommentare. Sie können vom Tool javadoc verarbeitet werden, um die API-Dokumentation für Ihre Klassen zu generieren. Der zweite ist ein normaler Blockkommentar.

19
manouti

Lesen Sie den Abschnitt .7 von JLS und erklären Sie 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 Zeichen ASCII/* bis zu den Zeichen ASCII */wird ignoriert (wie in C und C++).

  • //Text

Ein Kommentar zum Zeilenende: Der gesamte Text von den Zeichen ASCII // bis zum Zeilenende wird ignoriert (wie in C++).


Zu Ihrer 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 vom Tool zu generierenden Ausgabe angibt. Sie können ein Doclet schreiben, um jede Art von Textdatei-Ausgabe zu generieren, z. B. HTML, SGML, XML, RTF und MIF. Oracle bietet ein Standard-Doclet zum Generieren von API-Dokumentationen im HTML-Format. Mit Doclets können auch spezielle Aufgaben ausgeführt werden, die nicht mit der Erstellung der API-Dokumentation zusammenhängen.

Weitere Informationen zu Doclet finden Sie in API .

Der zweite Befehl ignoriert, wie in JLS klar erläutert, den gesamten Text zwischen /* und */ und wird daher zum Erstellen mehrzeiliger Kommentare verwendet.


Einige andere Dinge, die Sie über Kommentare in Java wissen möchten

  • Kommentare verschachteln nicht.
  • /* and */ haben in Kommentaren, die mit // beginnen, keine besondere Bedeutung.
  • // hat in Kommentaren, die mit /* or /** beginnen, keine besondere Bedeutung.
  • Die lexikalische Grammatik impliziert, dass Kommentare nicht in Zeichenliteralen ( §3.10.4 ) oder Zeichenkettenliteralen ( §3.10.5 ) vorkommen.

Daher ist der folgende Text ein einzelner vollständiger Kommentar:

/* this comment /* // /** ends here: */
14

Ich denke, die vorhandenen Antworten haben diesen Teil der Frage nicht angemessen beantwortet:

Wann sollte ich sie benutzen?

Wenn Sie eine API schreiben, die in Ihrer Organisation veröffentlicht oder wiederverwendet wird, sollten Sie umfassende Javadoc-Kommentare für jede public Klasse, Methode und jedes Feld sowie für protected Methoden und Felder von nicht schreiben -final Klassen. Javadoc sollte alles abdecken, was nicht von der Methodensignatur ü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 wahrscheinlich weniger wichtig. Für Wartungsprogrammierer sollten Sie jedoch Javadoc 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 einen Bezeichner bewegen, um alles zu erfahren, was er darüber wissen muss. Der ständige Verweis 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 möglicherweise nicht verwenden.

7
Kevin Krumwiede

Kommentare in der folgenden Auflistung von Java Code sind ausgegraute 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 Sprache Java unterstützt drei Arten von Kommentaren:

/* text */

Der Compiler ignoriert alles von /* bis */.

/** documentation */

Dies kennzeichnet einen Dokumentationskommentar (kurz Dokumentationskommentar). Der Compiler ignoriert diese Art von Kommentaren genauso wie Kommentare, die /* und */ verwenden. Das JDK-Javadoc-Tool verwendet Dokumentkommentare bei der Erstellung der automatisch generierten Dokumentation.

// text

Der Compiler ignoriert alles von // bis zum Zeilenende.

Überlegen Sie jetzt, wann Sie sie verwenden sollten:

Verwenden Sie // text, wenn Sie eine einzelne Codezeile kommentieren möchten.

Verwenden Sie /* text */, wenn Sie mehrere Codezeilen kommentieren möchten.

Verwenden Sie /** documentation */, wenn Sie Informationen zum Programm hinzufügen möchten, die für die automatische Generierung der Programmdokumentation verwendet werden können.

4
Raj

Als erstes definieren Sie Javadoc über Klassen, Interfaces, Methoden usw. 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 den Codeblock-Kommentar.

eine andere ist // dies, das Sie auf Anweisungsebene verwenden, um anzugeben, was die folgenden Codezeilen tun sollen.

Es gibt auch einige 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

3
sunny
  • Einzelkommentar z. B .: // Kommentar
  • Mehrzeiliger Kommentar, z. B .:/* Kommentar * /
  • javadoc-Kommentar, z. B .:/** Kommentar * /
0
Ramlal S