Komentarze¶

• Komentarze to tekst w kodzie źródłowym, który jest ignorowany przez kompilator.
• Komentarze służą programistom do wyjaśniania fragmentów kodu oraz w celu udokumentowania jego działania.
• Java posiada trzy rodzaje komentarzy:
  • // – dwa slashe rozpoczynają komentarz jednolinijkowy, który kończy się wraz z końcem linii,
  • /* */ – ten zestaw znaków służy do wstawiania komentarzy wielolinijkowych,
  • /** */ – w ten sposób wstawiamy do kodu komentarze dokumentacyjne, z których może zostać wygenerowana dokumentacja naszego kodu.
• Komentarzy nie należy nadużywać – powinniśmy, w pierwszej kolejności, pisać kod w taki sposób, by był czytelny.
• Komentarze warto stosować w celu wyjaśnienia nietrywialnych części kodu.
• Komentarzy wielolinijkowych nie wolno w sobie zagnieżdżać – poniższy fragment kodu jest nieprawidłowy – zawiera on zagnieżdżony komentarz wielolinijkowy:

  /*
    to jest komentarz wielolinijkowy
    /* a to jest kolejny, zagniezdzony komentarz */
  */
  

• Komentarze jednolinijkowe mogą być zawarte w komentarzach wielolinijkowych i na odwrót.
• Komentarzy nie powinno się umieszczać w stringach (literałach tekstowych) – zostaną one po prostu uznane za fragment literału tekstowego, a nie za komentarze:

  System.out.println("/* to nie jest komentarz! */ Witaj!");
  

Formatowanie kodu i najlepsze praktyki¶

• Kod źródłowy powinniśmy zapisywać w taki sposób, by był czytelny.
• Możemy w tym celu używać białych znaków – tabulacji, spacji, oraz nowych linii.
• Po napisaniu kodu warto zastanowić się, czy, zarówno my, jak i inni programiści, będą go rozumieli za tydzień/miesiąc?
• Najlepsze praktyki to zestaw konwencji, których przestrzeganie ma na celu pisanie kodu o wysokiej jakości. Oto kilka zasad, które warto stosować od początku nauki programowania:
  • piszemy jedną instrukcję na linię,
  • stosujemy wcięcia w blokach kodu,
  • stosujemy Camel Case, czyli nazwyWygladajaWTenSposob,
  • nazwy klasy zaczynamy wielką literą,
  • nie trzymamy zakomentowanego kodu w kodzie źródłowym,
  • używamy w kodzie języka angielskiego do nazywania obiektów, oraz w komentarzach.