/ ** i / * w komentarzach Java

Jaka jest różnica pomiędzy

/**
 * comment
 *
 *
 */

i

/*
 * 
 * comment
 *
 */

w Javie? Kiedy powinienem ich używać?

Pierwsza forma nazywa się Javadoc . Używasz tego, gdy piszesz formalne API dla twojego kodu, które są generowane przez javadocnarzędzie. Na przykład strona interfejsu API języka Java 7 korzysta z Javadoc i została wygenerowana przez to narzędzie.

Niektóre typowe elementy, które można zobaczyć w Javadoc to:

• @param: służy do wskazania, jakie parametry są przekazywane do metody i jaką wartość mają mieć

• @return: służy do wskazania wyniku, jaki metoda zwróci

• @throws: służy do wskazania, że ​​metoda zgłasza wyjątek lub błąd w przypadku niektórych danych wejściowych

• @since: służy do wskazania najwcześniejszej wersji Java, w której ta klasa lub funkcja była dostępna

Jako przykład, oto Javadoc dla comparemetody Integer:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

Druga forma to komentarz blokowy (wieloliniowy). Użyj tego, jeśli chcesz mieć wiele wierszy w komentarzu.

Powiem, że z drugiej formy chciałbyś korzystać tylko oszczędnie ; to znaczy, nie chcesz przeciążać kodu komentarzami blokowymi, które nie opisują, jakie zachowania powinna mieć metoda / funkcja złożona.

Ponieważ Javadoc jest bardziej opisowy, a dzięki temu można wygenerować rzeczywistą dokumentację, użycie Javadoc byłoby bardziej zalecane niż proste komentarze blokowe.

W przypadku języka programowania Java nie ma między nimi żadnej różnicy . Java ma dwa typy komentarzy: komentarze tradycyjne ( /* ... */) i komentarze na końcu wiersza ( // ...). Zobacz specyfikację języka Java . Tak więc, dla języka programowania Java, zarówno /* ... */i /** ... */są przypadki tradycyjnych komentarzach, i oba są traktowani dokładnie tak samo przez kompilator Javy, czyli są one ignorowane (lub bardziej poprawnie: są one traktowane jako spacje).

Jednak jako programista Java nie używasz tylko kompilatora Java. Używasz całego łańcucha narzędzi, który obejmuje np. Kompilator, IDE, system kompilacji itp. Niektóre z tych narzędzi interpretują rzeczy inaczej niż kompilator Java. W szczególności /** ... */komentarze są interpretowane przez narzędzie Javadoc, które jest zawarte na platformie Java i generuje dokumentację. Narzędzie Javadoc przeskanuje plik źródłowy Java i zinterpretuje części /** ... */jako dokumentację.

Jest to podobne do tagów takich jak FIXMEi TODO: jeśli dodasz komentarz podobny do // TODO: fix thislub // FIXME: do that, większość IDE podświetli takie komentarze, abyś o nich nie zapomniał. Ale w przypadku Javy są to tylko komentarze.

Pierwszy to komentarze Javadoc. Mogą być przetwarzane przez javadocnarzędzie do generowania dokumentacji API dla twoich klas. Drugi to zwykły komentarz blokowy.

Czytanie sekcji 3.7 JLS dobrze wyjaśnia wszystko, co musisz wiedzieć o komentarzach w Javie.

Istnieją dwa rodzaje komentarzy:

• / * tekst * /

Tradycyjny komentarz: cały tekst od znaków ASCII / * do znaków ASCII * / jest ignorowany (jak w C i C ++).

• //tekst

Komentarz na końcu wiersza: cały tekst od znaków ASCII // do końca wiersza jest ignorowany (jak w C ++).

O twoje pytanie,

Pierwszy

/**
 *
 */

służy do deklarowania technologii Javadoc .

Javadoc to narzędzie, które analizuje deklaracje i komentarze dokumentacji w zestawie plików źródłowych i tworzy zestaw stron HTML opisujących klasy, interfejsy, konstruktory, metody i pola. Możesz użyć docletu Javadoc, aby dostosować dane wyjściowe Javadoc. Doclet to program napisany za pomocą interfejsu API Docleta, który określa treść i format danych wyjściowych, które mają być generowane przez narzędzie. Możesz napisać dokument, aby wygenerować dowolny rodzaj pliku wyjściowego, np. HTML, SGML, XML, RTF i MIF. Oracle zapewnia standardowy dokument do generowania dokumentacji API w formacie HTML. Docletów można także używać do wykonywania specjalnych zadań niezwiązanych z tworzeniem dokumentacji API.

Aby uzyskać więcej informacji, Docletzapoznaj się z interfejsem API .

Drugi, jak wyjaśniono wyraźnie w JLS, zignoruje cały tekst pomiędzy /*i */dlatego jest używany do tworzenia komentarzy wielowierszowych.

Kilka innych rzeczy, które możesz chcieć wiedzieć o komentarzach w Javie

• Komentarze nie zagnieżdżają się.
• /* and */nie mają specjalnego znaczenia w komentarzach rozpoczynających się od //.
• //nie ma specjalnego znaczenia w komentarzach rozpoczynających się od /* or /**.
• Gramatyka leksykalna sugeruje, że komentarze nie występują w literałach znaków ( §3.10.4 ) ani literałach łańcuchowych ( §3.10.5 ).

Zatem poniższy tekst jest pojedynczym kompletnym komentarzem:

/* this comment /* // /** ends here: */

Nie sądzę, aby istniejące odpowiedzi odpowiednio uwzględniały tę część pytania:

Kiedy powinienem ich używać?

Jeśli piszesz interfejs API, który zostanie opublikowany lub ponownie wykorzystany w Twojej organizacji, powinieneś napisać obszerne komentarze Javadoc dla każdej publicklasy, metody i pola, a także protectedmetod i pól innych niż finalklasy. Javadoc powinien obejmować wszystko, czego nie może przekazać podpis metody, takie jak warunki wstępne, warunki dodatkowe, prawidłowe argumenty, wyjątki czasu wykonywania, wywołania wewnętrzne itp.

Jeśli piszesz wewnętrzny interfejs API (używany przez różne części tego samego programu), Javadoc jest prawdopodobnie mniej ważny. Jednak dla programistów zajmujących się konserwacją należy nadal pisać Javadoc dla dowolnej metody lub pola, w których prawidłowe użycie lub znaczenie nie jest od razu oczywiste.

„Zabójcza funkcja” Javadoc polega na tym, że jest ściśle zintegrowany z Eclipse i innymi IDE. Deweloper musi tylko najechać wskaźnikiem myszy na identyfikator, aby dowiedzieć się wszystkiego, co musi o nim wiedzieć. Ciągłe odwoływanie się do dokumentacji staje się drugą naturą doświadczonych programistów Java, co poprawia jakość własnego kodu. Jeśli Twój interfejs API nie jest udokumentowany za pomocą Javadoc, doświadczeni programiści nie będą chcieli go używać.

Komentarze w poniższej liście kodu Java to wyszarzone znaki:

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

Język Java obsługuje trzy rodzaje komentarzy:

/* text */

Kompilator ignoruje wszystko od /*do */.

/** documentation */

Oznacza komentarz do dokumentacji (w skrócie komentarz do dokumentu). Kompilator ignoruje tego rodzaju komentarze, tak jak ignoruje komentarze, które używają /*i */. Narzędzie JDK javadoc używa komentarzy doc podczas przygotowywania automatycznie generowanej dokumentacji.

// text

Kompilator ignoruje wszystko od //końca linii.

Teraz, kiedy powinieneś ich używać:

Użyj, // textjeśli chcesz skomentować pojedynczy wiersz kodu.

Użyj, /* text */jeśli chcesz skomentować wiele linii kodu.

Użyj, /** documentation */ gdy chcesz dodać informacje o programie, których można użyć do automatycznego generowania dokumentacji programu.

Pierwszym z nich jest Javadoc, który definiujesz na szczycie klas, interfejsów, metod itp. Możesz użyć Javadoc jako nazwy sugerującej, aby udokumentować kod na temat tego, co robi klasa lub jaką metodę robi itd. I wygenerować raport na jej temat.

Drugi to komentarz do bloku kodu. Załóżmy na przykład, że masz blok kodu, którego kompilator nie chce interpretować, a następnie używasz komentarza do bloku kodu.

innym jest // to, którego używasz na poziomie instrukcji, aby określić, co mają robić wiersze kodów.

Są też inne, takie jak // TODO, oznacza to, że chcesz zrobić coś później w tym miejscu

// FIXME, którego możesz użyć, gdy masz jakieś tymczasowe rozwiązanie, ale chcesz odwiedzić je później i ulepszyć.

Mam nadzieję że to pomoże

• Pojedynczy komentarz, np .: // komentarz
• Komentarz wieloliniowy np .: / * komentarz * /
• komentarz javadoc np .: / ** komentarz * /

Java obsługuje dwa typy komentarzy:

• /* multiline comment */: Kompilator ignoruje wszystko od /*do */. Komentarz może obejmować wiele wierszy.

• // single line: Kompilator ignoruje wszystko od //końca linii.

Niektóre narzędzia, takie jak javadoc, wykorzystują do tego celu specjalny komentarz wielowierszowy. Na przykład /** doc comment */komentarz do dokumentacji używany przez javadoc podczas przygotowywania automatycznie generowanej dokumentacji, ale dla Javy jest to prosty komentarz wielowierszowy.