Kommentare in Java: Nicht alles ist so einfach

Einführung

Kommentare - es scheint, dass es einfacher sein könnte und warum einen ganzen Artikel schreiben. Aber so einfach ist es nicht. Wie mein Chef sagte, kann jeder Code schreiben, aber einen guten Kommentar zu schreiben ist schwierig. Die meisten Sprachkurse beginnen mit dem traditionellen Hello World. Selbst in den Oracle-Tutorials beginnen wir im Abschnitt „Erste Schritte“ mit „Hallo Welt!“. Anwendung . Und schon in den ersten Codezeilen sehen wir sie – Java-Kommentare. Ihre Bedeutung wird auch dadurch unterstrichen, dass Kommentare in einem so wichtigen Dokument wie der Java Code Convention einen eigenen Abschnitt erhalten: Kommentare . Der Dokumentation zufolge werden Kommentare in Java in zwei Typen unterteilt:

• Implementierungskommentar (oder Codekommentar);
• Kommentar dokumentieren.

Codekommentare dienen zur Beschreibung einzelner Zeilen/Blöcke und Dokumentationskommentare dazu, die Spezifikation des Codes (seiner Schnittstelle) unabhängig von seiner Implementierung zu beschreiben. Java-Kommentare werden vom Compiler ignoriert, weil Sie machen für den Entwickler Sinn, nicht für den Benutzer. Daher können Sie die Größe kompilierter Klassen reduzieren.

Kommentare zum Java-Code

Aus dem Namen geht hervor, dass sich dieser Kommentar auf den Code bezieht und dessen Funktionen widerspiegeln sollte. Codekommentare sind:

• Kleinschreibung (d. h. in einer Zeile beschrieben)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Block (d. h. sie werden als ganzer Block beschrieben, da sie nicht in eine Zeile passen)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Ein interessantes Merkmal eines Blockkommentars ist, dass der Text dieses Blockkommentars nicht formatiert wird, wenn wir ihn mit „ /*- “ beginnen (d. h. ein Minuszeichen nach dem Sternchen hinzufügen). Interessant, aber mit Hilfe bestimmter Kommentare können Sie einige IDE-Hinweise geben. Mithilfe der Inline-Kommentare „ //@formatter:on “ und „ //@formatter:off “ in der Eclipse-IDE können Sie beispielsweise die Formatierung für Codeabschnitte deaktivieren. Sie müssen Kommentare sparsam und nur dort verwenden, wo es notwendig ist. Sie können beispielsweise einen Artikel zu diesem Thema lesen: „Schreiben Sie keine Kommentare zum Code!“ . Es gibt ein großartiges Buch mit dem Titel „ Clean Code: Creating, Analyzing, and Refactoring“ von Robert Martin. Es gibt ein eigenes Kapitel „Kommentare“. Als Epigraph zu diesem Kapitel ein ebenso hervorragendes Zitat: „Kommentieren Sie schlechten Code nicht – schreiben Sie ihn neu“ von Brian W. Kernighan und P. J. Plower. Dieses Kapitel ist auf Google Books zu finden . Die allgemeine Bedeutung lässt sich in einem Zitat von ihm ausdrücken:

Jedes Mal, wenn Sie einen Kommentar abgeben, zucken Sie zusammen und fühlen sich wie ein Versager.

Es ist klar, dass es keine absolute Wahrheit gibt und manchmal sind Kommentare notwendig. Aber es gibt immer Optionen und unnötige Kommentare müssen bekämpft werden. In diesem Kapitel werden auch ungewöhnliche Kommentare erwähnt, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

Ihr Sinn liegt darin, dass sie in der IDE auf besondere Weise gehandhabt werden können. In IDEA werden sie beispielsweise auf einer separaten Registerkarte gesammelt, wo Sie sie anzeigen können: Und ein kleines Rätsel mit einem Kommentar: Die Zeile „http://google.com“ ist eine gültige Zeile innerhalb der Methode, weil http ist hier eigentlich ein Tag und dann ein Kommentar. Viele Kommentare können oft von Codekommentaren bis hin zu Dokumentationskommentaren reichen, auf die wir später noch eingehen werden.

Kommentare zur Dokumentation

Dokumentationskommentare beschreiben die öffentliche API. API ist die Schnittstelle zur Anwendungsprogrammierung, also jene Klassen und Methoden, die anderen Entwicklern zur Ausführung beliebiger Aktionen zur Verfügung stehen. Kurz gesagt, diese Kommentare sollten erklären, warum diese oder jene Klasse und dieses Paket erstellt wurde und was diese oder jene Methode bewirkt. Bei Bedarf können Sie auch Klassenfelder beschreiben. Genau das sehen wir in den Tooltips unserer IDEs, die als JavaDoc dargestellt werden. Zum Beispiel: Wenn wir uns mit dieser Methode befassen, können wir sehen, woher dieser Text kommt: Sehen Sie sich auch hier die Java Code Convention: Code Convention an, um zu erfahren, wie Sie ein JavaDoc richtig formatieren . Sie ähneln in gewisser Weise den Blockkommentaren, werden jedoch anstelle eines Sternchens (nicht Asterix) zwei verwendet. Ein Beispiel für ein JavaDoc wurde oben angegeben. Es macht keinen Sinn, alle Möglichkeiten zu beschreiben, da darüber bereits in der offiziellen Oracle-Dokumentation geschrieben wird. Deshalb schauen wir uns alles, was Sie brauchen, in der offiziellen JavaDoc- Dokumentation im Abschnitt „Tag-Beschreibungen“ an. Oracle hat zu diesem Thema sogar ein separates Tutorial: How to Write Doc Comments for the Javadoc Tool . Tooltips in der IDE sind nett, aber aus gutem Grund sind sie eigentlich Dokumente. Basierend auf diesen JavaDoc-Kommentaren wird eine Dokumentation generiert. Hierfür gibt es ein spezielles Javadoc- Dienstprogramm . Wie wir sehen können, wird in diesem Tutorial darüber gesprochen. Eine Beschreibung zur Verwendung finden Sie auf der offiziellen Oracle-Website für JavaDoc . Um selbst zu sehen, wie das aussieht, können Sie im Verzeichnis ein Unterverzeichnis mit dem Namen des Pakets erstellen, zum Beispiel: test . Erstellen Sie eine einfache Klasse mit Kommentaren darin. Zum Beispiel:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Danach können wir den folgenden Befehl aus dem Verzeichnis ausführen, das unser Paketverzeichnis enthält: javadoc -d ./test test Danach sehen wir den Prozess der Dokumentationserstellung. Und dann können wir index.html öffnen, um das generierte Dokument anzuzeigen. Sie werden häufig sehen, dass API-Dokumentation veröffentlicht wird. Zum Beispiel die Spring Framework API .

Abschluss

Wie wir sehen, erweist sich eine so scheinbar einfache Sache wie Kommentare in Wirklichkeit als viel komplizierter. Wenn Sie also etwas Zeit mit Kommentaren verbringen und diese befolgen, wird Ihr Code besser und Sie werden als Programmierer wertvoller. #Wjatscheslaw