Komentarze w Javie: nie wszystko jest takie proste

Wstęp

Komentarze - wydawałoby się, że mogłoby być prościej i po co pisać cały artykuł. Ale to nie jest takie proste. Jak powiedział mój szef, każdy może napisać kod, ale napisanie dobrego komentarza jest trudne. Większość kursów językowych rozpoczyna się od tradycyjnego Hello World. Nawet w samouczkach Oracle, w sekcji „Pierwsze kroki” zaczynamy od „Hello World!” Aplikacja . I widzimy je już od pierwszych linijek kodu – komentarze Java. Ich wagę podkreśla także fakt, że w tak ważnym dokumencie jak konwencja Java Code, komentarzom poświęcony jest osobny rozdział: Komentarze . Zgodnie z dokumentacją komentarze w Javie dzielą się na dwa typy:

• komentarz do implementacji (lub komentarz do kodu);
• dokumentujący komentarz.

Komentarze do kodu służą do opisu poszczególnych linii/bloków, a komentarze do dokumentacji służą do opisu specyfikacji kodu (jego interfejsu) niezależnie od jego implementacji. Komentarze Java są ignorowane przez kompilator, ponieważ mają sens dla programisty, a nie dla użytkownika. Dlatego możesz zmniejszyć rozmiar skompilowanych klas.

Komentarze do kodu Java

Z nazwy jasno wynika, że ​​ten komentarz dotyczy kodu i powinien odzwierciedlać jego cechy. Komentarze do kodu to:

• Małe litery (tj. opisane w jednej linii)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Blok (czyli są opisane jako cały blok, ponieważ nie mieszczą się w jednej linii)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Ciekawostką komentarza blokowego jest to, że jeśli zaczniemy go od „ /*- ” (czyli dodamy znak minus po gwiazdce), to tekst tego komentarza blokowego nie zostanie sformatowany. Ciekawe, ale za pomocą niektórych komentarzy możesz dać kilka wskazówek IDE. Na przykład, używając wbudowanych komentarzy " //@formatter:on " i " //@formatter:off " w środowisku IDE Eclipse, możesz wyłączyć formatowanie sekcji kodu. Komentarzy należy używać oszczędnie i tylko wtedy, gdy jest to konieczne. Możesz na przykład przeczytać artykuł na ten temat: „Nie pisz komentarzy do kodu!” . Istnieje świetna książka pt. Czysty kod: tworzenie, analiza i refaktoryzacja autorstwa Roberta Martina. Zawiera osobny rozdział „Komentarze”. Jako motto do tego rozdziału, równie doskonały cytat: „Nie komentuj złego kodu – przepisz go” autorstwa Briana W. Kernighana i P. J. Plowera. Ten rozdział można znaleźć w Książkach Google . Ogólne znaczenie można wyrazić jednym cytatem z niego:

Za każdym razem, gdy skomentujesz, krzywisz się i czujesz, że poniosłeś porażkę.

Wiadomo, że nie ma prawdy absolutnej i czasem potrzebne są komentarze. Zawsze jednak istnieją opcje i należy walczyć ze zbędnymi komentarzami. W tym rozdziale wspomniano również o nietypowych komentarzach, DO ZROBIENIA:

// TODO: Добавить World
System.out.println("Hello, ");

Chodzi o to, że można je obsługiwać w specjalny sposób w IDE. Przykładowo w IDEA są one zebrane na osobnej zakładce, gdzie można je przeglądać: I mała zagadka z komentarzem: Linia „http://google.com” jest prawidłową linią wewnątrz metody, ponieważ http jest tutaj właściwie znacznikiem, a następnie komentarzem. Często wiele komentarzy może przejść od komentarzy do kodu do komentarzy do dokumentacji, o czym porozmawiamy później.

Komentarze do dokumentacji

Komentarze do dokumentacji opisują publiczny interfejs API. API to interfejs programowania aplikacji, czyli te klasy i metody, które są dostępne dla innych programistów w celu wykonywania dowolnych działań. Krótko mówiąc, te komentarze powinny wyjaśniać, dlaczego utworzono tę lub inną klasę i pakiet oraz co robi ta lub inna metoda. Jeśli to konieczne, możesz także opisać pola klas. To jest dokładnie to, co widzimy w etykietach narzędzi naszych IDE, które są prezentowane jako JavaDoc. Na przykład: Jeśli przejdziemy do tej metody, zobaczymy, skąd pochodzi ten tekst: Ponownie zobacz Konwencję kodu Java: Konwencja kodu , aby dowiedzieć się, jak poprawnie sformatować dokument JavaDoc . Są nieco podobne do komentarzy blokowych, ale zamiast jednej gwiazdki (nie Asterixa)) używane są dwie. Przykład JavaDoc podano powyżej. Nie ma sensu opisywać wszystkich możliwości, ponieważ jest to już napisane w oficjalnej dokumentacji Oracle. Dlatego wszystko, czego potrzebujesz, znajdziesz w oficjalnej dokumentacji JavaDoc , sekcja „Opisy tagów”. Oracle ma nawet osobny samouczek na ten temat: Jak pisać komentarze do dokumentów dla narzędzia Javadoc . Etykietki narzędzi w IDE są ładne, ale tak naprawdę nie bez powodu są dokumentami. Na podstawie tych komentarzy JavaDoc generowana jest dokumentacja. Służy do tego specjalne narzędzie javadoc . Jak widzimy, ten Tutorial mówi o tym. Opis sposobu korzystania z niego znajduje się na oficjalnej stronie Oracle dla JavaDoc . Aby samemu przekonać się jak to wygląda, możesz w katalogu utworzyć podkatalog z nazwą pakietu, np.: test . Utwórz prostą klasę z komentarzami. Na przykład:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Następnie możemy uruchomić następującą komendę z katalogu zawierającego nasz katalog pakietów: javadoc -d ./test test Następnie zobaczymy proces generowania dokumentacji. Następnie możemy otworzyć plik Index.html, aby zobaczyć wygenerowany dokument. Często będziesz widzieć publikowaną dokumentację API. Na przykład Spring Framework API .

Wniosek

Jak widzimy, tak pozornie prosta rzecz jak komentarze, w rzeczywistości okazuje się znacznie bardziej skomplikowana. Dlatego jeśli poświęcisz trochę czasu na komentarze i będziesz je śledzić, Twój kod będzie lepszy, a Ty będziesz bardziej wartościowy jako programista. #Wiaczesław