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

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

/**
 * comment
 *
 *
 */

и

/*
 * 
 * comment
 *
 */

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

ОТВЕТЫ

Ответ 1

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

Ответ 2

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

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

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

Ответ 3

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

Ответ 4

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

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

  • /* текст */

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

  • //текст

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

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

Первый

/**
 *
 */

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

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

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

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

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

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

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

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

Ответ 5

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

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

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

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

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

Ответ 6

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

Ответ 7

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

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

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

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

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

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

Ответ 8

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

Ответ 9

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

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

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

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