какая разница между
/**
* 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. Они могут быть обработаны
javadoc
инструментом для создания документации API для ваших классов. Второй - нормальный блочный комментарий.источник
Читая раздел 3.7 JLS, я объясню все, что вам нужно знать о комментариях в Java.
О вашем вопросе,
Первый
используется для объявления технологии Javadoc .
Для получения дополнительной информации
Doclet
обратитесь к API .Второй, как ясно объяснено в JLS, будет игнорировать весь текст между
/*
и,*/
таким образом, используется для создания многострочных комментариев.Некоторые другие вещи, которые вы могли бы знать о комментариях в Java
/* and */
не имеют особого значения в комментариях, которые начинаются с//
.//
не имеет особого значения в комментариях, которые начинаются с/* or /**
.Таким образом, следующий текст представляет собой один полный комментарий:
источник
Я не думаю, что существующие ответы адекватно адресовали эту часть вопроса:
Если вы пишете API, который будет опубликован или повторно использован в вашей организации, вы должны написать исчерпывающие комментарии Javadoc для каждого
public
класса, метода и поля, а такжеprotected
методов и полей не-final
классов. Javadoc должен охватывать все, что не может быть передано с помощью сигнатуры метода, например предусловия, постусловия, допустимые аргументы, исключения времени выполнения, внутренние вызовы и т. Д.Если вы пишете внутренний API (который используется разными частями одной и той же программы), Javadoc, возможно, менее важен. Но в интересах программистов по обслуживанию вы все равно должны писать Javadoc для любого метода или области, где правильное использование или значение не сразу очевидны.
«Убийственная особенность» Javadoc заключается в том, что он тесно интегрирован с Eclipse и другими IDE. Разработчику нужно только навести указатель мыши на идентификатор, чтобы узнать все, что ему нужно знать об этом. Постоянное обращение к документации становится второй натурой для опытных разработчиков Java, что улучшает качество их собственного кода. Если ваш API не задокументирован с помощью Javadoc, опытные разработчики не захотят его использовать.
источник
Комментарии в следующем листинге Java Code - это неактивные символы:
Язык Java поддерживает три вида комментариев:
Компилятор игнорирует все от
/*
до*/
.Это указывает на комментарий к документации (комментарий к документу, для краткости). Компилятор игнорирует такого рода комментарии, так же, как он игнорирует комментарии, которые используют
/*
и*/
. Инструмент JDK Javadoc использует комментарии к документам при подготовке автоматически сгенерированной документации.Компилятор игнорирует все, начиная
//
с конца строки.Теперь относительно того, когда вы должны их использовать:
Используйте,
// text
когда вы хотите прокомментировать одну строку кода.Используйте,
/* text */
когда вы хотите комментировать несколько строк кода.Используйте,
/** documentation */
если вы хотите добавить некоторую информацию о программе, которую можно использовать для автоматического создания программной документации.источник
Первый - для Javadoc, который вы определяете в верхней части классов, интерфейсов, методов и т. Д. Вы можете использовать Javadoc в качестве названия, предлагаемого для документирования вашего кода о том, что делает класс, что делает метод и т. Д., И генерировать отчет по нему.
Второй - комментарий блока кода. Например, у вас есть некоторый блок кода, который вы не хотите, чтобы компилятор интерпретировал, тогда вы используете комментарий блока кода.
// это то, что вы используете на уровне операторов, чтобы указать, что должны делать следующие строки кода.
Есть и другие, такие как // TODO, это будет означать, что вы хотите сделать что-то позже в этом месте
// FIXME вы можете использовать, когда у вас есть какое-то временное решение, но вы хотите посетить позже и сделать его лучше.
Надеюсь это поможет
источник
источник
Java поддерживает два типа комментариев:
/* multiline comment */
: Компилятор игнорирует все от/*
до*/
. Комментарий может занимать несколько строк.// single line
: Компилятор игнорирует все, начиная//
с конца строки.Некоторые инструменты, такие как javadoc, используют специальный многострочный комментарий для своих целей. Например
/** doc comment */
, комментарий к документации, используемый javadoc при подготовке автоматически сгенерированной документации, но для Java это простой многострочный комментарий.источник
/** .. */
обычного многострочного комментария, и первым символом внутри него оказывается звездочка.