Программирование на Java
Шрифт:
...
}
Часто блочные комментарии оформляют следующим образом (каждая строка начинается с *):
/*
* Описание алгоритма работы
* следующего цикла while
*/
while (x > 0) {
...
}
Блочный комментарий не обязательно должен располагаться на нескольких строках, он может даже находиться в середине оператора:
float s = 2Math.PI/*getRadius*/;
// Закомментировано для отладки
В этом примере
Комментарии не могут находиться в символьных и строковых литералах, идентификаторах (эти понятия подробно рассматриваются далее в этой лекции). Следующий пример содержит случаи неправильного применения комментариев:
// В этом примере текст /*…*/ станет просто
// частью строки s
String s = "text/*just text*/";
/*
Следующая строка станет причиной ошибки
при компиляции, так как комментарий разбил
имя метода getRadius
*/
circle.get/ comment*/Radius;
А такой код допустим:
// Комментарий может разделять вызовы функций:
circle./*comment*/getRadius;
// Комментарий может заменять пробелы:
int/*comment*/x=1;
В последней строке между названием типа данных int и названием переменной x обязательно должен быть пробел или, как в данном примере, комментарий.
Комментарии не могут быть вложенными. Символы /*, */ , // не имеют никакого особенного значения внутри уже открытых комментариев, как строчных, так и блочных. Таким образом, в примере
/ начало комментария /* // /** завершение: */
описан только один блочный комментарий. А в следующем примере (строки кода пронумерованы для удобства)
1. /*
2. comment
3. /*
4. more comments
5. */
6. finish
7. */
компилятор выдаст ошибку. Блочный комментарий начался в строке 1 с комбинации символов /*. Вторая открывающая комбинация /* на строке 3 будет проигнорирована, так как находится уже внутри комментария. Символы / в строке 5 завершат его, а строка 7 породит ошибку – попытка закрыть комментарий, который не был начат.
Любые комментарии полностью удаляются из программы во время компиляции, поэтому их можно использовать неограниченно, не опасаясь, что это повлияет на бинарный код. Основное их предназначение - сделать программу простой для понимания, в том числе и для других разработчиков, которым придется в ней разбираться по какой-либо причине. Также комментарии зачастую используются для временного исключения частей кода, например:
int x = 2;
int y = 0;
/* if (x > 0)
y = y + x*2;
else
y = -y - x*4; */
y = y y;// + 2*x;
В этом примере закомментировано выражение if-else и оператор сложения +2*x.
Как уже говорилось выше, комментарии можно писать символами Unicode, то есть на любом языке, удобном разработчику.
Кроме этого,
Комментарий разработчика записывается так же, как и блочный. Единственное различие в начальной комбинации символов – для документации комментарий необходимо начинать с /**. Например:
/**
* Вычисление модуля целого числа.
* Этот метод возвращает
* абсолютное значение аргумента x.
*/
int getAbs(int x) {
if (x>=0)
return x;
else
return -x;
}
Первое предложение должно содержать краткое резюме всего комментария. В дальнейшем оно будет использовано как пояснение этой функции в списке всех методов класса (ниже будут описаны все конструкции языка, для которых применяется комментарий разработчика).
Поскольку в результате создается HTML-документация, то и комментарий необходимо писать по правилам HTML. Допускается применение тегов, таких как <b> и . Однако теги заголовков с <h1> по <h6> и <hr> использовать нельзя, так как они активно применяются javadoc для создания структуры документации.
Символ в начале каждой строки и предшествующие ему пробелы и знаки табуляции игнорируются. Их можно не использовать вообще, но они удобны, когда необходимо форматирование, скажем, в примерах кода.
/**
* Первое предложение - краткое
* описание метода.
*
* Так оформляется пример кода:
* <blockquote>
* <pre>
* if (condition==true) {
* x = getWidth;
* y = x.getHeight;
* }
* </pre></blockquote>
* А так описывается HTML-список:
* <ul>
* <li>Можно использовать наклонный шрифт
* <i>курсив</i>,
* <li>или жирный <b>жирный</b>.
* </ul>
*/
public void calculate (int x, int y) {
...
}
Из этого комментария будет сгенерирован HTML-код, выглядящий примерно так:
Первое предложение – краткое описание метода.
Так оформляется пример кода:
if (condition==true) {
x = getWidth;
y = x.getHeight;
}
А так описывается HTML-список:
Можно использовать наклонный шрифт курсив,
или жирный жирный.
Наконец, javadoc поддерживает специальные теги. Они начинаются с символа @. Подробное описание этих тегов можно найти в документации. Например, можно использовать тег @see, чтобы сослаться на другой класс, поле или метод, или даже на другой Internet-сайт.