Komentarze Javy

Komentarze są częścią programu, która nie jest wykonywana. Kompilator po prostu ignoruje komentarze, ponieważ nie są do tego przeznaczone. Są napisane „ludzkim” językiem i mają na celu wyjaśnienie programu, części programu, pojedynczej linii lub metody dla programistów lub osób zaangażowanych w rozwój. Najczęściej komentarze pisane są po angielsku, jest to swego rodzaju tradycja. W tym artykule porozmawiamy o komentarzach w Javie i o tym, jak poprawnie ich używać, aby ułatwić życie Tobie i Twoim kolegom z zespołu.

Komentarze Java: dlaczego są ważne

Mówią, że programiści są wyjątkowo leniwi, jeśli chodzi o komentowanie własnego kodu. Jest to jednak bardzo ważna umiejętność, dlatego nie lekceważ jej, nawet jeśli dopiero zaczynasz naukę języka Java. Dobrze skomentowany kod jest znacznie cenniejszy niż kod bez komentarzy, ponieważ taki program jest znacznie łatwiejszy w utrzymaniu. Ponieważ duże projekty są najczęściej pisane w Javie, kompetentne komentowanie również przyspiesza rozwój, ponieważ programiście łatwiej jest radzić sobie z kodem innych osób. Komentarze są potrzebne, aby:

• Zrozum kod. Twoje lub kogoś innego. Jeśli wydaje Ci się, że nie musisz rozszyfrowywać własnego kodu, bo go napisałeś, spróbuj otworzyć stosunkowo skomplikowany program, który napisałeś miesiąc temu lub nawet wcześniej i szybko zrozumiej, co, gdzie i dlaczego miałeś na myśli. Komentarze mogą służyć do wyjaśniania logiki programu lub bloku programu, a także pozostawiania rekomendacji dla tych, którzy będą później pracować z Twoim kodem. Tego typu komentarz można nazwać wyjaśniającym.

• Zawierające informacje o przeznaczeniu obiektów, parametrach wejściowych i wyjściowych (jeśli istnieją), dane o deweloperze i inne ważne rzeczy związane z fragmentem kodu. Takie komentarze znajdują się w nagłówkach modułów, bibliotek, procedur i funkcji. Można je nazwać komentarzami do dokumentacji.

• Kontroluj błędy i ulepszaj kod. Wątpliwy kod lub kod wymagający ulepszenia można zawsze skomentować i ponownie przejrzeć później. Jeżeli przychodzi Ci do głowy, że jakiś problem można rozwiązać w inny sposób, ale teraz nie masz na to czasu, napisz ten pomysł w komentarzu. W przeciwnym razie najprawdopodobniej pod presją nowego kodu zapomnisz o tym.

Rodzaje komentarzy w Javie

Pomimo tego, że w komentarzach możesz pisać wszystko, w Javie istnieją pewne typy komentarzy i zasady ich używania. W komentarzach Java zimno być:

• Komentarze jednowierszowe
• Komentarze wielowierszowe
• Komentarze do dokumentacji

Komentarze jednowierszowe

Najpopularniejszymi komentarzami w Javie są komentarze jednowierszowe. Aby wskazać taki komentarz wystarczy postawić podwójny ukośnik przed tekstem // . Komentarze jednowierszowe są oznaczane tylko na początku komentarza. Komentarz trwa do końca wiersza. Składnia:

//here is a single line comment.

Weźmy przykład tego typu komentarzy Java:

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
   }
}

Dane wyjściowe to: Zwykle jednoliniowy komentarz znajduje się nad lub pod komentowanym miejscem w programie, czasami w tej samej linii. Ważne jest, aby wizualnie było jasne, czego dotyczy komentarz.

Komentarze wielowierszowe

Czasami nie wystarczy jedna linia, aby napisać komentarz Java. Na przykład musisz opisać sposób działania metody lub złożoną formułę, którą wdrażasz. W takim przypadku możesz napisać kilka komentarzy jednoliniowych, ale bardziej racjonalne byłoby napisanie tak zwanych komentarzy wieloliniowych. Są one oznaczone po obu stronach symbolami /* */ . Składnia komentarzy wielowierszowych:

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

Spójrzmy na przykład komentarzy wielowierszowych w kodzie

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"));
   }
}

Komentarze do dokumentacji Java

Jest to specjalny typ komentarzy Java używany do generowania strony dokumentacji. Zwykle programiści piszą komentarze do dokumentacji przy użyciu Javadoc, generatora dokumentacji służącego do generowania dokumentacji API w formacie HTML z kodu źródłowego Java. Format dokumentów używany przez Javadoc to branżowy standard dokumentowania klas Java, a najpopularniejsze IDE, takie jak IntelliJ IDEA i Eclipse, automatycznie generują Javadoc HTML. Komentarze do dokumentacji Java mają następującą składnię:

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

@author  Java Developer
*/

Oto przykład: jest to fragment klasy Java Short . Przy okazji, możesz spojrzeć na dowolny kod klasy Java ze swojego IDE (na przykład w IntelliJ IDEA z Windows po prostu naciśnij ctrl+LBM lub ctrl + b (w Windows) na nazwie dowolnej klasy lub metody).

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")

Oto kod Java znanej i lubianej przez wszystkich nowicjuszy metody println() z takim komentarzem:

/**
* 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 ma kilka specjalnych znaczników Javadoc oznaczonych @, które można zobaczyć w powyższym kodzie. Przykładem takiego znacznika Javadoc jest @author, który dodaje nazwę autora klasy. Kolejnym znacznikiem Javadoc jest @, ponieważ dodaje komentarz wskazujący, że ta klasa jest używana od określonej wersji Java. Pisanie dobrych dokumentów Javadoc wymaga wiedzy i doświadczenia (i cierpliwości!). Więcej informacji na temat Javadoc można znaleźć w oficjalnej dokumentacji Jak pisać komentarze do dokumentów dla narzędzia Javadoc .

PS kilka zabawnych przykładów komentarzy z prawdziwego życia

/**
*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;
}

Aby utrwalić zdobytą wiedzę, sugerujemy obejrzenie lekcji wideo z naszego kursu Java