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

192

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

/**
 * comment
 *
 *
 */

и

/*
 * 
 * comment
 *
 */

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

Devender
источник

Ответы:

242

Первая форма называется 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 было бы более предпочтительным, чем простые блочные комментарии.

Makoto
источник
35
Еще одним приятным преимуществом использования Javadoc вместо простых блочных комментариев является то, что когда вы помещаете Javadoc-комментарий перед элементом Java (например, сигнатура метода, объявление поля, класс и т. Д.), Это позволяет использовать интегрированные среды разработки - по крайней мере, Eclipse - показать ваш комментарий (например, во всплывающей подсказке), когда вы перемещаете курсор - или наводите курсор мыши - на ссылку на этот элемент Java.
SantiBailors
Можно ли использовать комментарии к документации Java для переменных?
the_prole
@the_prole: Вы можете, но я не вижу в этом особой ценности, если он не является частью пакета Constants. Даже тогда, комментарии в строке были более ценными в моем опыте.
Макото
136

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

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

Это похоже на теги, подобные FIXMEи TODO: если вы добавите комментарий типа // TODO: fix thisили // FIXME: do that, большинство IDE выделят такие комментарии, чтобы вы не забыли о них. Но для Java они просто комментарии.

Hoopje
источник
48
+1 за то, что я сделал важное различие в том, что синтаксис Javadoc не является частью языка, который в настоящее время не найден ни одним другим ответом.
Крис Хейс
1
Вот почему у вас может быть проект, который прекрасно компилируется в Maven, но как только вы решите присоединить JavaDocs, он начинает жаловаться, потому что javadocинструмент не может что-то интерпретировать.
Капитан Мэн
19

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

М Аноути
источник
14

Читая раздел 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: */
Жан-Франсуа Савар
источник
8

Я не думаю, что существующие ответы адекватно адресовали эту часть вопроса:

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

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

Если вы пишете внутренний API (который используется разными частями одной и той же программы), Javadoc, возможно, менее важен. Но в интересах программистов по обслуживанию вы все равно должны писать Javadoc для любого метода или области, где правильное использование или значение не сразу очевидны.

«Убийственная особенность» Javadoc заключается в том, что он тесно интегрирован с Eclipse и другими IDE. Разработчику нужно только навести указатель мыши на идентификатор, чтобы узнать все, что ему нужно знать об этом. Постоянное обращение к документации становится второй натурой для опытных разработчиков Java, что улучшает качество их собственного кода. Если ваш API не задокументирован с помощью Javadoc, опытные разработчики не захотят его использовать.

Кевин Крумвиде
источник
4

Комментарии в следующем листинге 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 */ если вы хотите добавить некоторую информацию о программе, которую можно использовать для автоматического создания программной документации.

Радж
источник
3

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

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

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

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

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

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

солнечно
источник
0
  • Один комментарий, например: // комментарий
  • Многострочный комментарий, например: / * комментарий * /
  • Javadoc комментарий, например: / ** комментарий * /
Рамлал С
источник
4
Это ничего не добавляет к существующим ответам.
Шмосел
1
@shmosel нет, это суммирует их, хотя.
Det
-2

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

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

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

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

Ranjeet
источник
12
Язык Java поддерживает только два типа комментариев. Комментарий в виде /** .. */обычного многострочного комментария, и первым символом внутри него оказывается звездочка.
Крис Хейс