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

В чем разница между

/** * comment * * */ 

а также

 /* * * comment * */ 

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

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

Некоторые общие элементы, которые вы увидите в Javadoc, include:

  • @param : это используется, чтобы указать, какие параметры передаются методу, и какое значение у них ожидается

  • @return : это используется, чтобы указать, какой результат метод собирается вернуть

  • @throws : это используется, чтобы указать, что метод генерирует исключение или ошибку в случае определенного ввода

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

В качестве примера, вот Javadoc для метода compare Integer :

 /** * Compares two {@code int} values numerically. * The value returned is identical to what would be returned by: * 
 * Integer.valueOf(x).compareTo(Integer.valueOf(y)) * 

* * @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 и интерпретирует части между /** ... */ как документацией.

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

Первый комментарий Javadoc. Их можно обработать с помощью инструмента javadoc для создания документации API для ваших classов. Второй – это нормальный комментарий блока.

Чтение раздела 3.7 JLS хорошо объясняет все, что вам нужно знать о комментариях на Java.

Есть два вида комментариев:

  • / * текст * /

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

  • //текст

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


О вашем вопросе,

Первый

 /** * */ 

используется для объявления технологии Javadoc .

Javadoc – инструмент, который анализирует объявления и комментарии документации в наборе исходных файлов и создает набор HTML-страниц, описывающих classы, интерфейсы, конструкторы, методы и поля. Вы можете использовать Javadoc doclet для настройки вывода Javadoc. Документ – это программа, написанная с помощью API Doclet, которая определяет контент и формат вывода, который должен быть сгенерирован инструментом. Вы можете написать doclet для создания любых выходных текстовых файлов, таких как HTML, SGML, XML, RTF и MIF. Oracle предоставляет стандартный документ для создания документации HTML-формата HTML. Доклеты также могут использоваться для выполнения специальных задач, не связанных с созданием документации API.

Для получения дополнительной информации о Doclet обратитесь к API .

Второй, как объясняется в JLS, будет игнорировать весь текст между /* и */ поэтому используется для создания многострочных комментариев.


Некоторые другие вещи, которые вы, возможно, захотите узнать о комментариях в Java

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

Таким образом, следующий текст является одним полным комментарием:

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

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

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

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

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

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

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

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

другой – // это вы используете на уровне инструкции, чтобы указать, что должны делать исходящие строки кодов.

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

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

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

Комментарии в следующем списке 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 */ 

Это указывает на комментарий к документации (комментарий к доктору, для краткости). Компилятор игнорирует этот комментарий, так же как игнорирует комментарии, которые используют /* и */ . Инструмент javadoc JDK использует комментарии doc при подготовке автоматически созданной документации.

 // text 

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

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

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

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

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

  • Один комментарий, например: // комментарий
  • Комментарий Multi Line, например: / * comment * /
  • Комментарий javadoc например: / ** комментарий * /

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

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

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

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

Interesting Posts
Давайте будем гением компьютера.