Rozdział 2 - Komentarze i formatowanie kodu - Komentarze

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.
Komentarze mogą zostać użyte w każdej częsci programu.

Rodzaje komentarzy

W Javie istnieją trzy 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żane, tzn. /* komentarz /* zagniezdzony */ */ jest niepoprawny i spodowuje 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żane. 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żego z trzech powyższych rodzajów:

Nazwa pliku: HelloWorldZKomentarzami.java
/*
 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:

Witaj Swiecie! Witajcie ponownie!

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 */).

W rozdziale o metodach powiemy sobie więcej o komentarzach dokumentacyjnych, gdzie nauczymy się, jak można je wykorzystywać do dokumentowania metod.

Zagnieżdżanie komentarzy

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

Nazwa pliku: ZagniezdzoneKomentarzeJednolinijkowe.java
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:

Nazwa pliku: ZagniezdzoneKomentarzeWielolinijkowe.java
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:

ZagniezdzoneKomentarzeWielolinijkowe.java:6: error: illegal start of expression */ ^ ZagniezdzoneKomentarzeWielolinijkowe.java:6: error: illegal start of expression */ ^ 2 errors

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:

Nazwa pliku: ZagniezdzoneKomentarze.java
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ą:

Nazwa pliku: KomentarzWStringu.java
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:

/* wypisujemy powitanie */ Witaj!

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?

Komentarzy nie należy nadużywać – powinny być unikane zawsze, kiedy to możliwe – kod w pierwszej kolejności powinien być czytelny. Wiele osób traktuje komentarze w kodzie jako ostateczność. Należy wypracować sobie pewien balans stanowiący kiedy warto, a kiedy nie powinno się, użyć komentarza.

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 wprowdzenia błędów do kodu przez innego programistę, który może nie zdawać sobie sprawy, dlaczego kod jest taki a nie inny?

Dodaj komentarz

Twój adres email nie zostanie opublikowany.