Java-Kommentare

Kommentare sind der Teil eines Programms, der nicht ausgeführt wird. Der Compiler ignoriert Kommentare einfach, da sie nicht dafür gedacht sind. Sie sind in „menschlicher“ Sprache verfasst und sollen das Programm, einen Teil des Programms, eine einzelne Zeile oder Methode für Entwickler oder an der Entwicklung beteiligte Personen erklären. Am häufigsten werden Kommentare auf Englisch verfasst, das ist eine Art Tradition. In diesem Artikel sprechen wir über Kommentare in Java und wie man sie richtig verwendet, um Ihnen und Ihren Teamkollegen das Leben zu erleichtern.

Java-Kommentare: Warum sie wichtig sind

Man sagt, Programmierer seien extrem faul, wenn es darum gehe, ihren eigenen Code zu kommentieren. Dies ist jedoch eine sehr wichtige Fähigkeit, also unterschätzen Sie sie nicht, auch wenn Sie gerade erst anfangen, Java zu lernen. Gut kommentierter Code ist viel wertvoller als Code ohne Kommentare, da ein solches Programm viel einfacher zu warten ist. Da große Projekte meist in Java geschrieben werden, beschleunigt kompetentes Kommentieren auch die Entwicklung, da es für einen Programmierer einfacher ist, mit dem Code anderer Leute umzugehen. Kommentare sind erforderlich, um:

• Verstehe den Code. Deines oder das eines anderen. Wenn Sie den Eindruck haben, dass Sie Ihren eigenen Code nicht entschlüsseln müssen, weil Sie ihn geschrieben haben, versuchen Sie, ein relativ komplexes Programm zu öffnen, das Sie vor einem Monat oder sogar früher geschrieben haben, und verstehen Sie schnell, was, wo und warum Sie im Sinn hatten. Kommentare können verwendet werden, um die Logik eines Programms oder Programmblocks zu erklären und Empfehlungen für diejenigen zu hinterlassen, die später mit Ihrem Code arbeiten. Diese Art von Kommentar kann als erklärend bezeichnet werden.

• Enthält Informationen über den Zweck von Objekten, Eingabe- und Ausgabeparameter (falls vorhanden), Daten über den Entwickler und andere wichtige Dinge im Zusammenhang mit dem Codefragment. Solche Kommentare befinden sich in den Kopfzeilen von Modulen, Bibliotheken, Prozeduren und Funktionen. Sie können als Dokumentationskommentare bezeichnet werden.

• Kontrollieren Sie Fehler und verbessern Sie den Code. Fragwürdiger Code oder Code, der verbessert werden muss, kann jederzeit auskommentiert und später noch einmal überprüft werden. Wenn Ihnen in den Sinn kommt, dass ein bestimmtes Problem auch anders gelöst werden kann, Sie jetzt aber keine Zeit dafür haben, schreiben Sie diese Idee in den Kommentar. Andernfalls werden Sie es höchstwahrscheinlich unter dem Druck des neuen Codes vergessen.

Arten von Kommentaren in Java

Obwohl Sie in den Kommentaren alles und jedes schreiben können, gibt es in Java bestimmte Arten von Kommentaren und Regeln für deren Verwendung. In Java-Kommentaren kann es sein:

• Einzeilige Kommentare
• Mehrzeilige Kommentare
• Kommentare zur Dokumentation

Einzeilige Kommentare

Die häufigsten Java-Kommentare sind einzeilige Kommentare. Um einen solchen Kommentar zu kennzeichnen, genügt es, vor dem Text // einen doppelten Schrägstrich zu setzen . Einzeilige Kommentare werden nur am Anfang des Kommentars gekennzeichnet. Der Kommentar wird bis zum Ende der Zeile fortgesetzt. Syntax:

//here is a single line comment.

Nehmen wir ein Beispiel für diese Art von Java-Kommentaren:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

Die Ausgabe ist: Normalerweise steht ein einzeiliger Kommentar oberhalb oder unterhalb der kommentierten Stelle im Programm, gelegentlich auch in derselben Zeile. Wichtig ist, dass visuell klar erkennbar ist, worauf sich der Kommentar bezieht.

Mehrzeilige Kommentare

Manchmal reicht eine Zeile nicht aus, um einen Java-Kommentar zu schreiben. Sie müssen beispielsweise die Funktionsweise einer Methode oder eine komplexe Formel beschreiben, die Sie implementieren. In diesem Fall können Sie mehrere einzeilige Kommentare schreiben, sinnvoller wäre es jedoch, sogenannte mehrzeilige Kommentare zu schreiben. Sie sind auf beiden Seiten mit den Symbolen /* */ gekennzeichnet . Syntax mehrzeiliger Kommentare:

/*This comment
is
Multi line comment
we can describe here
what we need */

Sehen wir uns ein Beispiel für mehrzeilige Kommentare im Code an

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Kommentare zur Java-Dokumentation

Dies ist eine spezielle Art von Java-Kommentaren, die zum Generieren einer Dokumentationsseite verwendet werden. Normalerweise schreiben Entwickler Dokumentationskommentare mit Javadoc, einem Dokumentationsgenerator zum Generieren von API-Dokumentation im HTML-Format aus Java-Quellcode. Das von Javadoc verwendete Dokumentformat ist der Industriestandard für die Dokumentation von Java-Klassen und die beliebtesten IDEs wie IntelliJ IDEA und Eclipse generieren automatisch Javadoc-HTML. Kommentare zur Java-Dokumentation haben die folgende Syntax:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

Hier ist ein Beispiel: Es ist ein Fragment der Java Short- Klasse. Übrigens können Sie sich jeden Java-Klassencode aus Ihrer IDE ansehen (zum Beispiel drücken Sie in IntelliJ IDEA unter Windows einfach Strg+LBM oder Strg+B (in Windows) auf den Namen einer beliebigen Klasse oder Methode).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

Hier ist der Java-Code der bekannten und von allen Neulingen geliebten println()- Methode mit folgendem Kommentar:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc verfügt über einige spezielle Javadoc-Tags, die mit @ markiert sind, wie Sie im obigen Code sehen können. Ein Beispiel für ein solches Javadoc-Tag ist @author, das einen Namen des Klassenautors hinzufügt. Ein weiteres Javadoc-Tag ist @since. Es fügt einen Kommentar hinzu, der angibt, dass diese Klasse seit der angegebenen Java-Version verwendet wird. Das Schreiben guter Javadoc-Dokumente erfordert Wissen und Erfahrung (und Geduld!). Weitere Informationen zu Javadoc finden Sie in der offiziellen Dokumentation How to Write Doc Comments for the Javadoc Tool .

PS: einige lustige Kommentarbeispiele aus dem wirklichen Leben

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

Um das Gelernte zu vertiefen, empfehlen wir Ihnen, sich eine Videolektion aus unserem Java-Kurs anzusehen