/ ** и / * в Java Комментарии

какая разница между

/**
 * comment
 *
 *
 */

и

/*
 * 
 * comment
 *
 */

на Яве? Когда я должен их использовать?

Первая форма называется 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 Code - это неактивные символы:

/** 
 * 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 использует комментарии к документам при подготовке автоматически сгенерированной документации.

// text

Компилятор игнорирует все, начиная //с конца строки.

Теперь относительно того, когда вы должны их использовать:

Используйте, // textкогда вы хотите прокомментировать одну строку кода.

Используйте, /* text */когда вы хотите комментировать несколько строк кода.

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

Первый - для Javadoc, который вы определяете в верхней части классов, интерфейсов, методов и т. Д. Вы можете использовать Javadoc в качестве названия, предлагаемого для документирования вашего кода о том, что делает класс, что делает метод и т. Д., И генерировать отчет по нему.

Второй - комментарий блока кода. Например, у вас есть некоторый блок кода, который вы не хотите, чтобы компилятор интерпретировал, тогда вы используете комментарий блока кода.

// это то, что вы используете на уровне операторов, чтобы указать, что должны делать следующие строки кода.

Есть и другие, такие как // TODO, это будет означать, что вы хотите сделать что-то позже в этом месте

// FIXME вы можете использовать, когда у вас есть какое-то временное решение, но вы хотите посетить позже и сделать его лучше.

Надеюсь это поможет

• Один комментарий, например: // комментарий
• Многострочный комментарий, например: / * комментарий * /
• Javadoc комментарий, например: / ** комментарий * /

Java поддерживает два типа комментариев:

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

• // single line: Компилятор игнорирует все, начиная //с конца строки.

Некоторые инструменты, такие как javadoc, используют специальный многострочный комментарий для своих целей. Например /** doc comment */, комментарий к документации, используемый javadoc при подготовке автоматически сгенерированной документации, но для Java это простой многострочный комментарий.