Korrekte Verwendung von Anmerkungen in Java

Java bietet drei Arten von Kommentaren:

Einzeilige Kommentare (C++-Stil)

Die einfachsten Kommentare in Java sind einzeilige Kommentare. Es beginnt mit zwei Schrägstrichen und endet am Ende der Zeile. Zum Beispiel:

// this is a single-line comment
 
x = 1; // a single-line comment after code

Mehrzeilige Kommentare (C-Stil)

Java bietet auch Kommentartypen, die sich über mehrere Zeilen erstrecken. Diese Art von Kommentar beginnt mit einem Schrägstrich gefolgt von einem Sternchen und endet mit einem Sternchen gefolgt von einem Schrägstrich. Die Start- und Endtrennzeichen für diesen Kommentartyp können in derselben Zeile oder in verschiedenen Zeilen stehen. Zum Beispiel:

/* This is a c-style comment */
 
/*  This is also a
 
    c-style comment, spanning
 
    multiple lines */

Hinweis: Kommentare im C-Stil können nicht verschachtelt werden. Beispielsweise die folgende Verwendung:

/* A comment looks like
   /* This is a comment */
   blah blah blah
 */

Die obige Verwendung führt zu einem Syntaxfehler, da der Java-Compiler nur das erste */ als Kommentar behandelt. (Der Compiler geht davon aus, dass der Kommentar mit dem ersten „*/“ endet.)

Sie können einzeilige Kommentare in mehrzeilige Kommentare einbetten:

/* This is a single-line comment:
 
    // a single-line comment
 
 */

und mehrzeilige Kommentare in einzeiligen Kommentaren verwenden:

// /* this is
 
//    a multi-line
 
//    comment */

Dokumentationskommentare

Dokumentationskommentare sind spezielle Kommentare, die mehrzeiligen Kommentaren sehr ähnlich sind. Sie können zur Erstellung einer externen Dokumentation für Ihren Quellcode verwendet werden. Dieser Kommentar beginnt mit einem Schrägstrich gefolgt von zwei Sternchen und endet mit einem Sternchen gefolgt von einem Schrägstrich. Zum Beispiel:

/** This is a documentation comment */
 
/** This is also a
 
    documentation comment */

Hier sind einige wichtige Dinge, die Sie bei Dokumentationskommentaren beachten sollten:

Der Javadoc-Dokumentationsgenerator fügt den gesamten Text in den Dokumentationskommentaren hinzu ein HTML-Absatz. Das bedeutet, dass jeder Text in einem Dokumentationskommentar als Absatz formatiert wird; Leerzeichen und Zeilenumbrüche werden ignoriert. Wenn Sie eine spezielle Formatierung wünschen, müssen Sie HTML-Tags in Dokumentationskommentaren verwenden.

Wenn ein Dokumentationskommentar mit mehr als zwei Sternchen beginnt, geht Javadoc davon aus, dass diese Sternchen verwendet werden, um einen „Kasten“ um den Kommentar im Quellcode zu erstellen, und ignoriert die zusätzlichen Sternchen. Zum Beispiel:

/**********************************
 
   This is the start of a method
 
**********************************/

Dieser Kommentar behält nur den Text „Dies ist der Anfang einer Methode“.

javadoc ignoriert Sternchen am Zeilenanfang in Dokumentationskommentaren. Beispiel:

/***************************************
 
 * This is a doc comment
 
 * on multiple lines that I want to stand
 
 * out in source code, looking "neat"
 
 ***************************************/

Dieser Kommentar enthält nur den Text „Dies ist ein Dokumentkommentar über mehrere Zeilen, den ich im Quellcode hervorheben möchte und der „ordentlich“ aussieht“.

Übliche Verwendung ist wie folgt:

/******************************************
 
   ...
 
 ******************************************/

Diese Verwendung dient der Hervorhebung des Kommentars. Beachten Sie, dass es sich hierbei um einen Dokumentationskommentar handelt (auch wenn es nicht Ihrer Meinung nach ist) und der Inhalt des Kommentars in der generierten Dokumentation erscheint.

Wann Dokumentationskommentare verwendet werden sollten

Sie sollten Dokumentationskommentare (mindestens) vor allen öffentlichen Klassen, Schnittstellen, Methoden und Klassen- oder Instanzvariablen im Quellcode verwenden. Dadurch kann Javadoc eine einfache Dokumentation für den Code generieren, die die öffentlichen Entitäten und eine kurze Beschreibung jeder Entität auflistet. Sie können Dokumentationskommentare auch vor nicht öffentlichen Methoden verwenden, müssen jedoch eine Javadoc-Option verwenden, um sie zu dokumentieren. Die Verwendung von Dokumentationskommentaren für nicht öffentliche Entitäten ist weniger wichtig als für öffentliche Entitäten (deren Schnittstelle ist nicht verfügbar ...). Wenn Sie jedoch Code kommentieren möchten, können Sie auch Dokumentationskommentare verwenden.

Wann sollten einzeilige Kommentare verwendet werden?

Jederzeit!

In Bezug auf Kommentare habe ich einen einfachen Vorschlag: Verwenden Sie einzeilige Kommentare, wenn Sie reguläre Kommentare schreiben möchten (keine Dokumentationskommentare, die Klassen, Schnittstellen, Methoden oder Variablen beschreiben).

Warum? Denn Sie können Ihr Codesegment einfach mit mehrzeiligen Kommentaren „auskommentieren“ („Code auskommentieren“ bedeutet, den lexikalischen Status eines Codeabschnitts in einen Kommentar zu ändern, sodass der Compiler diesen Codeabschnitt ignorieren kann). Zum Beispiel:

x = 1;   /* set x to 1 */
 
y = 2;   /* set y to 2 */
 
f(x, y); /* call f with x and y */

要把上面三行代码注释掉，你可能需要在每一行的前面使用单行注释：

// x = 1;   /* set x to 1 */
 
// y = 2;   /* set y to 2 */
 
// f(x, y); /* call f with x and y */

或者在还没有加注释的地方加上多行注释：

/* x = 1;  */ /* set x to 1 */
 
/* y = 2;  */ /* set y to 2 */
 
/* f(x, y);*/ /* call f with x and y */

或者分解或删除已存在的注释的“结束注释”分解符：

/*
 
x = 1;   /* set x to 1 * /
 
y = 2;   /* set y to 2 * /
 
f(x, y); /* call f with x and y * /
 
*/

这些用法都糟糕透了。如果原始代码使用下面的注释，那么事情就好办多了：

x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y

如此一来，只需使用多行注释把代码围起来你就可以轻松把它注释掉：

/*
 
x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y
 
*/

在你需要使用注释的时候尽量使用单行注释，不要写无用的注释。

你也可以看看之前发布的9个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

阅读了上面的内容后，这个问题变得很明显了。只使用多行注释来注释代码段，不要用以其他目的。