/ ** і / * в коментарях Java

Яка різниця між

/**
 * comment
 *
 *
 */

і

/*
 * 
 * comment
 *
 */

на Java? Коли я повинен їх використовувати?

Перша форма називається Javadoc . Ви використовуєте це під час написання формальних API для свого коду, які генеруються javadocінструментом. Наприклад, сторінка API Java 7 використовує Javadoc і була створена цим інструментом.

Деякі поширені елементи, які ви бачите в Javadoc, включають:

• @param: це використовується для вказівки, які параметри передаються методу та яке значення вони мають мати

• @return: це використовується для вказівки того, який результат дасть метод

• @throws: це використовується, щоб вказати, що метод видає виняток або помилку у випадку певного введення

• @since: це використовується для вказівки на найдавнішу версію Java, у якій цей клас або функція була доступна

Як приклад, ось Javadoc для compareметоду 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);
}

Друга форма - це блоковий (багаторядковий) коментар. Ви використовуєте це, якщо ви хочете мати в коментарі кілька рядків.

Я скажу, що ви хотіли б використовувати останню форму лише ощадливо ; тобто ви не хочете перевантажувати свій код коментарями блоків, які не описують, якою поведінкою має бути метод / комплексна функція.

Оскільки Javadoc є більш описовим з цих двох, і ви можете генерувати фактичну документацію в результаті її використання, використання Javadoc було б більш переважно, ніж прості коментарі блоків.

Для Java мови програмування , немає ніякої різниці між ними. У Java є два типи коментарів: традиційні коментарі ( /* ... */) та коментарі в кінці рядка ( // ...). Див . Специфікацію мови Java . Отже, для мови програмування Java обидва /* ... */і /** ... */є примірниками традиційних коментарів, і вони обидва трактуються точно однаково Java-компілятором, тобто їх ігнорують (або правильніше: вони трактуються як пробіл).

Однак, як програміст Java, ви не використовуєте лише компілятор Java. Ви використовуєте цілий ланцюжок інструментів, який включає, наприклад, компілятор, IDE, систему збирання тощо. І деякі з цих інструментів інтерпретують речі інакше, ніж компілятор Java. Зокрема, /** ... */коментарі інтерпретуються інструментом Javadoc, який входить у платформу Java та створює документацію. Інструмент Javadoc сканує вихідний файл Java та інтерпретує частини між ними /** ... */як документацію.

Це схоже на теги типу : FIXMEта TODOякщо ви додасте коментар, як, // TODO: fix thisабо // FIXME: do thatбільшість IDE виділять такі коментарі, щоб ви не забували про них. Але для Java це лише коментарі.

Перший - це коментарі Javadoc. Вони можуть бути оброблені javadocінструментом для створення документації API для ваших класів. Другий - це звичайний блоковий коментар.

Читаючи розділ 3.7 JLS, добре поясніть все, що вам потрібно знати про коментарі на Java.

Існує два типи коментарів:

• / * текст * /

Традиційний коментар: весь текст від символів ASCII / * до символів ASCII * / ігнорується (як у C та C ++).

• // текст

Зауваження в кінці рядка: весь текст від символів ASCII // до кінця рядка ігнорується (як у C ++).

Щодо вашого питання,

Перший

/**
 *
 */

використовується для оголошення технології Javadoc .

Javadoc - це інструмент, який аналізує декларації та коментарі до документації у наборі вихідних файлів та створює набір HTML-сторінок, що описують класи, інтерфейси, конструктори, методи та поля. Ви можете використовувати доклет Javadoc для налаштування виводу Javadoc. Доклет - це програма, написана за допомогою API Doclet, яка визначає зміст та формат виводу, який повинен бути створений інструментом. Ви можете написати доклетту для створення будь-якого виду текстових файлів, таких як HTML, SGML, XML, RTF та MIF. Oracle надає стандартний доклет для створення документації API у форматі HTML. Доклетів також можна використовувати для виконання спеціальних завдань, не пов'язаних з виготовленням документації API.

Для отримання додаткової інформації Docletзверніться до API .

Другий, як чітко пояснено в JLS, буде ігнорувати весь текст між ними /* і, */таким чином, використовується для створення багаторядкових коментарів.

Деякі інші речі, які ви можете знати про коментарі на Java

• Коментарі не гніздяться.
• /* and */ не мають особливого значення в коментарях, які починаються з // .
• // не має особливого значення в коментарях, які починаються з /* or /** .
• З лексичної граматики випливає, що коментарі не трапляються в символьних літералах ( §3.10.4 ) або рядкових літералах ( §3.10.5) ).

Таким чином, наступний текст - це єдиний повний коментар:

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

Я не думаю, що існуючі відповіді адекватно вирішили цю частину питання:

Коли я повинен їх використовувати?

Якщо ви пишете API, який буде опублікований або повторно використаний у вашій організації, ви повинні написати вичерпні коментарі Javadoc для кожного publicкласу, методу та поля, а також protectedметодів та полів некласів final. Javadoc повинен охоплювати все, що не може передати підписом методу, такі як передумови, постумови, дійсні аргументи, винятки під час виконання, внутрішні виклики тощо.

Якщо ви пишете внутрішній API (той, який використовується різними частинами однієї програми), Javadoc, мабуть, менш важливий. Але для вигоди програмістів з технічного обслуговування, ви все одно повинні написати Javadoc для будь-якого методу чи поля, де правильне використання чи значення не відразу очевидні.

"Особливістю вбивці" Javadoc є те, що він тісно інтегрований з Eclipse та іншими IDE. Розробнику потрібно лише навести курсор миші на ідентифікатор, щоб дізнатися про нього все, що потрібно знати. Постійне звернення до документації набуває другого характеру для досвідчених розробників Java, що покращує якість власного коду. Якщо ваш API не задокументований з Javadoc, досвідчені розробники не захочуть його використовувати.

Коментарі в наступному переліку Java-коду - це сірі символи:

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

Мова Java підтримує три види коментарів:

/* text */

Компілятор ігнорує все від /*до */.

/** documentation */

Це вказує на коментар до документації (коментар док, коротко). Компілятор ігнорує такий тип коментарів, як і ігнорує коментарі, які використовують /*і */. Інструмент JDK javadoc використовує коментарі doc при підготовці автоматично створеної документації.

// text

Компілятор ігнорує все від //кінця рядка.

Тепер щодо того, коли вам слід користуватися ними:

Використовуйте, // textколи ви хочете коментувати один рядок коду.

Використовуйте /* text */ коли ви хочете коментувати кілька рядків коду.

Використовуйте, /** documentation */ коли ви хочете додати інформацію про програму, яка може бути використана для автоматичного створення програмної документації.

По-перше, це для Javadoc, який ви визначаєте у верхній частині класів, інтерфейсів, методів і т. Д. Ви можете використовувати Javadoc в якості назви, щоб запропонувати для документування коду те, що робить клас чи метод, і т.д.

Другий - коментування блоку коду. Скажімо, наприклад, у вас є блок коду, який ви не хочете інтерпретувати, тоді ви використовуєте коментар до кодового блоку.

інший // це ви використовуєте на рівні заяви, щоб вказати, що слід робити рядки кодів.

Є ще деякі, наприклад // TODO, це означатиме, що ви хочете зробити щось пізніше на цьому місці

// FIXME, який ви можете використовувати, коли у вас є тимчасове рішення, але ви хочете відвідати пізніше та покращити його.

Сподіваюся, це допомагає

• Один коментар, наприклад: // коментар
• Багаторядковий коментар, наприклад: / * коментар * /
• коментар javadoc, наприклад: / ** коментар * /

Java підтримує два типи коментарів:

• /* multiline comment */: Компілятор ігнорує все, починаючи /*з */. Коментар може охоплювати декілька рядків.

• // single line: Компілятор ігнорує все від //кінця рядка.

Деякі інструменти, такі як javadoc, використовують для своїх цілей спеціальний багаторядковий коментар. Наприклад /** doc comment */, коментар до документації, який використовує javadoc під час підготовки автоматично сформованої документації, але для Java це простий багаторядковий коментар.