Komentarze są fragmentami kodu źródłowego, które są całkowicie pomijane przez kompilator. Możemy w nich umieścić dowolny tekst. Komentarze piszemy zarówno dla innych programistów, jak i dla nas samych.

Komentarze:

1. są dobrym sposobem na wyjaśnianie, dlaczego coś zostało zrobione tak, a nie inaczej,
2. są wykorzystywane do wytłumaczenia bardziej skomplikowanych fragmentów kodu bądź opisu zastosowanych tricków,
3. są także używane do dokumentowania metod.

Rodzaje komentarzy¶

1. jednolinijkowe – zaczynają się od dwóch znaków slash // i kończą się wraz z końcem linii,
2. wielolinijkowe – zaczynają się od znaków /* oraz kończą znakami */ – nie mogą być w sobie zagnieżdżone, tzn. /* komentarz /* zagniezdzony */ */ jest niepoprawny i spowoduje zakończenie kompilacji programu błędem,
3. wielolinijkowe-dokumentacyjne – zaczynają się od znaków /** oraz kończą znakami */ Również nie mogą być w sobie zagnieżdżone. Istnieją narzędzia, które z odpowiednich komentarzy dokumentacyjnych w kodzie są w stanie wygenerować dokumentację. Jest to popularne rozwiązanie w języku Java – w ten właśnie sposób generowana jest dokumentacja JavaDoc, o której opowiedzieliśmy sobie w jednym z poprzednich rozdziałów.

Spójrzmy na nasz pierwszy program z dodanymi komentarzami każdego z trzech powyższych rodzajów:

/*
 To jest komentarz wielolinijkowy.
 Ponizej zaczyna sie klasa HelloWorldZKomentarzami
*/
public class HelloWorldZKomentarzami {
  /**
   * To jest komentarz dokumentujacy, jak dziala metoda main.
   */
  public static void main(String[] args) {
    // to jest komentarz jednolinijkowy - ponizej wypisujemy tekst
    System.out.println("Witaj Swiecie!"); // na koncu linii moze byc komentarz

    /*
       Ponizsza linia kodu nie zostanie wykonana, poniewaz
       zostala zakomentowana.
    */
    // System.out.println("Witajcie!");

    System.out.println(/* kolejny komentarz */ "Witajcie ponownie!");
  }
}

Ten program spowoduje wypisanie na ekran następujących komunikatów:

Powyższy przykład zawiera wiele komentarzy – po kolei:

Trzy komentarze jednolinijkowe:

// to jest komentarz jednolinijkowy - ponizej wypisujemy tekst
System.out.println("Witaj Swiecie!"); // na koncu linii moze byc komentarz

// System.out.println("Witajcie!");

Komentarze jednolinijkowe kończą się wraz z końcem linii – nic nie stoi na przeszkodzie, by umieścić je po instrukcji, tak jak w przypadku drugiej linii powyżej.

Zauważmy także, że w ostatniej linii komentarz rozpoczyna się już na początku – mimo, iż treścią komentarza jest instrukcja wypisania na ekran tekstu Witajcie!, instrukcja ta zostanie zignorowana przez kompilator, ponieważ z punktu widzenia kompilatora jest to komentarz, a kompilatora komentarze w ogóle nie interesują.

Trzy komentarze wielolinijkowe:

/*
 To jest komentarz wielolinijkowy.
 Ponizej zaczyna sie klasa HelloWorldZKomentarzami
*/
public class HelloWorldZKomentarzami {

/*
   Ponizsza linia kodu nie zostanie wykonana, poniewaz
   zostala zakomentowana.
*/
// System.out.println("Witajcie!");

System.out.println(/* kolejny komentarz */ "Witajcie ponownie!");

Pierwszy komentarz wielolinijkowy jest przed początkiem klasy, a drugi znajduje się w metodzie main. Najciekawszy jest trzeci komentarz wielolinijkowy – znajduje się on bowiem wewnątrz wywołania wypisywania na ekran tekstu – nie stanowi to dla kompilatora problemu, ponieważ całkowicie omija on komentarze.

Jeden komentarz dokumentacyjny:

/**
 * To jest komentarz dokumentujacy, jak dziala metoda main.
 */
public static void main(String[] args) {

O tym, że jest to komentarz dokumentacyjny świadczy to, iż rozpoczyna się od znaków /** a nie /*. Na razie nie będziemy stosować komentarzy tego typu – wystarczą nam komentarze jednolinijkowe (zaczynające się od znaków //) i wielolinijkowe (zaczynające się od znaków /* a kończące */).

Zagnieżdżanie komentarzy¶

Komentarze jednolinijkowe mogą być w sobie zagnieżdżone, w przeciwieństwie do komentarzy wielolinijkowych (oraz komentarzy dokumentacyjnych) – spójrzmy na poniższy przykład:

public class ZagniezdzoneKomentarzeJednolinijkowe {
  public static void main(String[] args) {
    // wypisz komunikat // wypisz tekst
    System.out.println("Testujemy komentarze jednolinijkowe");
  }
}

Powyższy program skompiluje się bez problemów, a w wyniku uruchomienia go, na ekranie zobaczymy komunikat "Testujemy komentarze jednolinijkowe".

Z kolei, próba kompilacji poniższego programu zakończy się błędem – kompilator zaprotestuje:

public class ZagniezdzoneKomentarzeWielolinijkowe {
  public static void main(String[] args) {
    /*
      to jest komentarz wielolinijkowy
      /* a to jest kolejny, zagniezdzony komentarz */
    */
    System.out.println("Testujemy komentarze wielolinijkowe");
  }
}

Kompilator zasygnalizuje następujące problemy:

Problem wynika z próby zagnieżdżenia w sobie komentarzy wielolinijkowych.

Warto jeszcze wspomnieć, że komentarze jednolinijkowe mogą być zawarte w komentarzach wielolinijkowych, oraz na odwrót – poniższy kod jest poprawny:

public class ZagniezdzoneKomentarze {
  public static void main(String[] args) {
    // komentarze jednolinijkowy /* inny komentarz */

    /*
      komentarz wielolinijkowy
      // druga linia
      trzecia linia
    */
  }
}

Komentarze w stringach¶

Komentarze w kodzie źródłowym można umieścić prawie wszędzie – wyjątkiem są stringi (czyli literały tekstowe zawarte między cudzysłowami " "), ponieważ umieszczenie komentarza (jedno- bądź wielolinijkowego) w stringu spowoduje, że będzie on jego częścią:

public class KomentarzWStringu {
  public static void main(String[] args) {
    System.out.println("/* wypisujemy powitanie */ Witaj!");
  }
}

Powyższy program kompiluje się poprawnie, chociaż po uruchomieniu na ekranie zobaczymy:

To, co umieszczamy w literałach tekstowych, "traci" swoje specjalne znaczenie – kompilator nie traktuje w powyższym przypadku znaków /* i */ jako początku i końca komentarza wielolinijkowego, lecz, po prostu, jako zwykły tekst, fragment stringa, który chcemy wypisać na ekran.

Kiedy używać komentarzy?¶

Gdy piszemy kod, warto zastanowić się:

• czy za miesiąc będę wiedział/a, dlaczego użyta została taka konstrukcja w kodzie?
• czy za miesiąc będę wiedział/a, jak działa dany fragment kodu?
• czy za miesiąc będę wiedział/a, dlaczego w kodzie znajduje się coś, co na pierwszy rzut oka wydaje się zbędne bądź nieintuicyjne?
• czy napisanie komentarza pomoże w zrozumieniu kodu innemu programiście?
• czy napisanie komentarza zapobiegnie wprowadzenia błędów do kodu przez innego programistę, który może nie zdawać sobie sprawy, dlaczego kod jest taki a nie inny?