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

Вернемся к нашей первой программе на 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, а также способы передачи управления в вашей программе.