Брюс Эккель - Философия Java3

@param

Полезен при документировании методов. Форма использования:

@param имя-параметра описание

где имя-параметра — это идентификатор в списке параметров метода, а описание — текст описания, который можно продолжить на несколько строк. Описание считается завершенным, когда встретится новый тег. Можно записывать любое количество тегов @param, по одному для каждого параметра метода.

©return

Форма использования:

©return описание

где описание объясняет, что именно возвращает метод. Описание может состоять из нескольких строк.

@throws

Исключения будут рассматриваться в главе 9. В двух словах это объекты, которые можно «возбудить» (throw) в методе, если его выполнение потерпит неудачу. Хотя при вызове метода создается всегда один объект исключения, определенный метод может вырабатывать произвольное количество исключений, и все они требуют описания. Соответственно, форма тега исключения такова:

©throws полное-имя-класса описание

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

@deprecated

Тег используется для пометки устаревших возможностей, замещенных новыми и улучшенными. Он сообщает о том, что определенные средства программы не следует использовать, так как в будущем они, скорее всего, будут убраны. В Java SE5 тег @deprecated был заменен директивой @Deprecated (см. далее).

Пример документации

Вернемся к нашей первой программе на Java, но на этот раз добавим в нее комментарии со встроенной документацией:

//: object/Hel1oDate.java import java util.*;

/** Первая программа-пример книги.

* Выводит строку и текущее число.

* ^author Брюс Эккель

* ^author www.MindView net

* (Aversion 4.0 */

public class HelloDate {

/** Точка входа в класс и приложение

* @param args Массив строковых аргументов

* @throws exceptions Исключения не выдаются */

public static void main(String[] args) {

System out.printlnCTIpMBeT. сегодня: "); System.out.println(new DateO);

}

} /* Output. (55* match) Привет, сегодня. Wed Oct 05 14:39:36 MDT 2005 */// ~

В первой строке файла использована моя личная методика помещения специального маркера //: в комментарий как признака того, что в этой строке комментария содержится имя файла с исходным текстом. Здесь указывается путь к файлу (object означает эту главу) с последующим именем файла 1. Последняя строка также завершается комментарием (///:~), обозначающим конец исходного текста программы. Он помогает автоматически извлекать из текста книги программы для проверки компилятором и выполнения.

Тег /* Output: обозначает начало выходных данных, сгенерированных данным файлом. В этой форме их можно автоматически проверить на точность.

В данном случае значение (55% match) сообщает системе тестирования, что результаты будут заметно отличаться при разных запусках программы. В большинстве примеров книги результаты приводятся в комментариях такого вида, чтобы вы могли проверить их на правильность.

Стиль оформления программ

Согласно правилам стиля, описанным в руководстве Code Conventions for the Java Programming Language имена классов должны записываться с прописной буквы. Если имя состоит из нескольких слов, они объединяются (то есть символы подчеркивания не используются для разделения), и каждое слово в имени начинается с большой буквы:

class А11TheColorsOfTheRainbow { // ..

Практически для всего остального: методов, полей и ссылок на объекты — используется такой же способ записи, за одним исключением — первая буква идентификатора записывается строчной. Например:

class AllTheColorsOfTheRainbow {

int anlntegerRepresentingColors; void changeTheHueOfTheColor(int newHue) { II ...

}

// .

}

Помните, что пользователю ваших классов и методов придется вводить все эти длинные имена, так что будьте милосердны.

В исходных текстах Java, которые можно увидеть в библиотеках фирмы Sun, также используется схема размещения открывающих и закрывающих фигурных скобок, которая встречается в примерах данной книги.

Резюме

В этой главе я постарался привести информацию о программировании на Java, достаточную для написания самой простой программы. Также был представлен обзор языка и некоторых его основных свойств. Однако примеры до сих пор имели форму «сначала это, потом это, а после что-то еще». В следующих двух главах будут представлены основные операторы, используемые при программировании на Java, а также способы передачи управления в вашей программе.

Операторы

На нижнем уровне операции с данными в Java осуществляются посредством операторов.