Java 7 - [11]

Именно так создается документация к JDK.

Добавим комментарии к нашему примеру (листинг 1.2).

Листинг 1.2. Первая программа с комментариями

/**

* Разъяснение содержания и особенностей программы...

* @author Имя Фамилия (автора)

* @version 1.0 (это версия программы)

*/

class HelloWorld{ // HelloWorld — это только имя // Следующий метод начинает выполнение программы

public static void main(String[] args){ // args не используются /* Следующий метод просто выводит свой аргумент * на экран дисплея */

System.out.println("Hello, XXI Сentury World!");

// Следующий вызов закомментирован,

// метод не будет выполняться

// System.out.println("Farewell, XX Сentury!");

}

}

Звездочки в начале строк не имеют никакого значения, они написаны просто для выделения комментария. Пример, конечно, перегружен пояснениями (это плохой стиль), здесь просто показаны разные формы комментариев.

Аннотации

Обратите внимание на комментарий, приведенный в начале листинга 1.2. В него вставлены указания-теги @author и @version утилите javadoc. Просматривая текст этого комментария и встретив какой-либо из тегов, утилита javadoc выполнит предписанные тегом действия. Например, тег @see предписывает сформировать гиперссылку на другой документ HTML, а тег @deprecated, записанный в комментарий перед методом, вызовет пометку этого метода в документации как устаревшего.

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

Использование таких утилит стало общепризнанной практикой, и, начиная с пятой версии Java SE, было решено ввести прямо в компилятор возможность обрабатывать теги, которые получили название аннотаций. Аннотации записываются не внутри комментариев вида /**...*/, а непосредственно в том месте, где они нужны. Например, после того как мы запишем непосредственно перед заголовком какого-либо метода аннотацию @Deprecated, компилятор будет выводить на консоль предупреждение о том, что этот метод устарел и следует воспользоваться другим методом. Обычно замена указывается тут же, в этом же комментарии.

Несколько аннотаций, количество которых увеличивается с каждой новой версией JDK, объявлено прямо в компиляторе. Ими можно пользоваться без дополнительных усилий. Мы будем вводить их по мере надобности. Кроме них разработчик может объявить и использовать в своем приложении свои аннотации. Как это делается, рассказано в главе 3.

Константы

В языке Java можно записывать константы различных типов в разных видах. Форма записи констант почти полностью заимствована из языка С. Перечислим все разновидности констант.

Целые

Целые константы можно записывать в четырех системах счисления:

□ в привычной для нас десятичной форме: +5, -7, 12345678;

□ в двоичной форме, начиная с нуля и латинской буквы b или b: 0b1001, 0B11011;

□ в восьмеричной форме, начиная с нуля: 027, -0326, 0777 (в записи таких констант недопустимы цифры 8 и 9);

ЗАмЕчАниЕ

Целое число, начинающееся с нуля, трактуется как записанное в восьмеричной форме, а не в десятичной.

□ в шестнадцатеричной форме, начиная с нуля и латинской буквы x или x: 0xff0a, 0xFC2D, 0X45a8, 0X77FF (здесь строчные и прописные буквы не различаются).

Для улучшения читаемости группы цифр в числе можно разделять знаком подчеркивания: 1_001_234, 0xFC_2D.

Целые константы хранятся в оперативной памяти в формате типа int (см. далее).

В конце целой константы можно записать латинскую букву "L" (прописную L или строчную l), тогда константа будет сохраняться в длинном формате типа long (см. далее): +25L, -037l, 0xffL, 0XDFDFl.

Совет

Не используйте при записи длинных целых констант строчную латинскую букву l, ее легко спутать с единицей.

Действительные

Действительные константы записываются только в десятичной системе счисления в двух формах:

□ с фиксированной точкой: 37.25, -128.678967, +27.035;

□ с плавающей точкой: 2.5e34, -0.345e-25, 37.2E+4; можно писать строчную или прописную латинскую букву E; пробелы и скобки недопустимы.

В конце действительной константы можно поставить букву F или f, тогда константа будет сохраняться в оперативной памяти в формате типа float (см. далее): 3.5f, -4 5.67F, 4.7e-5f. Можно приписать и букву D (или d): 0.04 5D, -456.77889d, означающую тип double, но это излишне, поскольку действительные константы и так хранятся в формате типа double.

Символы

Одиночные символы записываются в апострофах, чтобы отличить их от имен переменных. Для записи символов используются следующие формы:

□ печатные символы, записанные на клавиатуре, просто записываются в апострофах (одинарных кавычках): 'a', 'N', '?';

□ управляющие и специальные символы записываются в апострофах с обратной наклонной чертой, чтобы отличить их от обычных символов: