скачать книгу бесплатно
Javadoc просматривает вашу программу, ища строки, начинающиеся с косой черты и двух звездочек, и создает HTML-документацию.
Но почему мы должны использовать этот комментарий?
Вместо поиска комментариев в миллионах строк кода, вы можете открыть веб-страницу и найти всю важную информацию о программе.
Когда мы говорим в Java об автоматической генерации документации, мы используем термин Javadoc.
Какую информацию мы должны включить в Javadoc?
На сайте Oracle вы можете найти руководство по эффективной практике написания комментариев для инструмента Javadoc.
Мы попытаемся обобщить наиболее важные из них, используя пример.
Мы начнем с определения Javadoc-комментария.
Комментарий Javadoc написан в формате HTML и должен предшествовать коду.
Он состоит из двух частей: описания и блока тегов.
Рассмотрим теги, которые вы должны использовать и как их использовать.
Давайте посмотрим на метод, который здесь указан, и вид информации, которая должна быть предоставлена для него в Javadoc.
Вы должны начать свой комментарий Javadoc с краткого и полного описания того, что делает этот метод.
Если в вашем Javadoc-комментарии есть несколько абзацев, разделите их тэгом p.
Затем вставьте пустую строку комментария, между описанием и блоком тегов.
Обратите внимание, что каждый комментарий Javadoc имеет только одно описание.
И как только инструмент Javadoc найдет пустую строку, он решит, что описание закончено.
Затем вы используете теги для добавления информации о вашем методе.
Наконец, вы должны поместить в конце строку со звездочкой и косой чертой, чтобы отметить конец комментария Javadoc.
Какая информация должна быть включена в блок тегов?
Для описания метода нам понадобятся, в основном, два типа тегов – @param и @return.
@param описывает аргумент метода.
И его необходимо указать для всех аргументов метода.
За тегом всегда следует имя аргумента.
Это имя всегда указывается в нижнем регистре.
Затем идет описание аргумента.
Далее вы должны всегда указывать тип данных аргумента.
Единственным исключением является тип данных, int, который вы можете опустить.
Чтобы разделить имя, описание и тип данных аргумента, вы можете добавить один или несколько пробелов.
Теги @param должны быть перечислены в порядке объявления аргумента.
Что касается описания, если это фраза без глагола, начните его с маленькой буквы.
Если это предложение с глаголом, начните его с заглавной буквы.
Таким образом, Javadoc – это полезный инструмент, который позволяет программистам автоматически генерировать HTML-страницы с документацией из их кода.
Исключения
Когда мы говорили о том, что мы можем сделать в случае метода, который не определен для всех возможных входных значений, мы сказали, что мы можем запрограммировать, что нужно сделать в исключительной ситуации.
То есть мы можем программировать, что делать в обычных случаях, и что делать в исключительных случаях.
Это сделает нашу программу более надежной.
Таким образом, у нас есть исключения.
В этом случае мы используем не комментарии, а используем конструкции программирования языка Java.
Мы программируем, что делать для значений, которые не желательны.
Часто бывает, что наши программы хорошо написаны, их синтаксис и последовательность инструкций верны.
И они прекрасно компилируются.
Но когда мы их запускаем, возникают ошибки.
Java обрабатывает ошибки, возникающие в наших программах, во время выполнения с использованием исключений.
Oracle определяет исключения как события, которые происходят во время выполнения программы, и которые нарушают нормальный поток выполнения инструкций.
Однако важно учитывать, что совсем не плохо иметь программы, которые выбрасывают исключения.
Исключения позволяют отделить основную логику программы от действий, которые нужно предпринять, когда происходит что-то необычное.
Кроме того, исключения позволяют классифицировать и дифференцировать типы ошибок систематическим образом.
Таким образом, исключение – это ошибка, возникающая во время выполнения программы. Исключения могут возникать во многих случаях, например:
Пользователь ввел некорректные данные.
Или файл, к которому обращается программа, не найден.
Или сетевое соединение с сервером было утеряно во время передачи данных.
Рассмотрим некоторые из наиболее распространенных исключений в программах Java, а также механизм их обработки, чтобы обеспечить нормальный поток программы, даже если во время выполнения происходят ошибки.
Первое исключение, которое мы здесь видим, это ArithmeticException.
Это исключение выбрасывается при возникновении арифметических ошибок, например, при делении целого на ноль.
Эти сегменты кода вызывают исключение ArithmeticException.
Если вы программируете метод, в котором вы используете математическое деление, вы всегда должны проверять, что делитель отличается от нуля, так как вы не знаете, какие значения будут иметь аргументы, которые вы принимаете в этом методе.
Другим распространенным исключением является ArrayIndexOutOfBoundsException.
Это исключение вызывается, когда пытаются получить доступ к элементу массива с недействительным индексом.
Если мы определим, например, четырехэлементный массив, то это исключение будет выбрасываться при попытке доступа к элементу массива с индексом четыре или выше, а также при попытке доступа к элементу массиву с отрицательным индексом.
Поэтому, когда метод должен получить доступ к элементу в массиве, важно сначала проверить, что нужная позиция находится в пределах массива.
Еще одно исключение, это NumberFormatException.
Это исключение вызывается, когда пытаются преобразовать строку в числовой тип, например, double или integer, но при этом строка не содержит числа.
Стандартный способ управления этими инструкциями, которые могут выбросить исключение, это заключить их в оператор try-catch.
Здесь вы видите, что код метода printDivision заключен в выражение try-catch.
В этом случае нет необходимости проверять значение b, делителя.
Если b отличен от нуля, будет выполнен метод System.out.printIn (a / b);
В противном случае Java выбросит исключение ArithmeticException с сообщением, что вы не можете делить на ноль.
Поток программы будет продолжен, как обычно, после обнаружения этого исключения.
Выражение try-catch также может быть применено к примерам ArrayIndexOutOfBoundsException и NumberFormatException, которые мы видели ранее.
В обоих случаях, и благодаря выражению try-catch, мы можем гарантировать, что, если возникает исключение, пользователь получит соответствующую информацию, и поток выполнения программы продолжится далее нормально.
Вы также можете не обрабатывать исключения блоком try-catch в методе, а передать это право вызывающему этот метод.
В этом случае вы используете ключевое слово throws, которое прописывается в сигнатуре метода, и обозначающее что этот метод потенциально может выбросить исключение с указанным типом.
И уже в вызывающем коде обработать вызов этого метода блоком try-catch.
Также вы можете сами, специально, не виртуальная машина, а вы – выбросить исключение с помощью ключевого слова throw, указав тип исключения.
Например, чтобы предотвратить выполнение кода, когда параметр метода не является возможным входным значением.
Таким образом, ключевое слово throw – служит для генерации исключений.
Блок try может иметь несколько блоков catch, каждый из которых имеет дело с конкретным исключением.
Если блок try генерирует исключение, то соответствующий блок catch обработает исключение, и программа будет продолжена.
Встроенные исключения Java имеют определенную иерархию.
Все классы, представляющие ошибки являются наследниками класса java.lang.Throwable.
Только объекты этого класса или его наследников могут быть «выброшены» JVM при возникновении какой-нибудь исключительной ситуации, а также только эти исключения могут быть «выброшены» во время выполнения программы с помощью ключевого слова throw.
Поэтому, если вы хотите создать свой класс исключения, он должен происходить от класса Throwable, или более точнее от класса Exception.
Также нужно учитывать, что все исключения делятся на «проверяемые» (checked) и «непроверяемые» (unchecked).
checked exception – проверяемое исключение, которое проверяется компилятором.
Throwable и Exception и все их наследники, за исключением наследников Error-а и RuntimeException – проверяемые.
Error и RuntimeException и все их наследники – не проверяемые компилятором исключения.
Компилятор при компиляции проверяет код на возможность выброса при выполнении кода проверяемого исключения.
И так как проверяемое исключение проверяется во время компиляции, возникнет ошибка компиляции, если проверяемое исключение не обработано блоком try-catch, или оно не объявлено в заголовке или сигнатуре метода с помощью ключевого слова throws.
Так почему не все исключения являются проверяемыми?
Дело в том, что если проверять каждое место, где теоретически может быть ошибка, то ваш код сильно разрастется, и станет плохо читаемым.
И язык Java будет полностью непригодным для использования в качестве языка программирования.
Например, в любом месте, где происходит деление чисел, нужно было бы проверять на исключение ArithmeticException, потому что возможно деление на ноль.
Эту проверку создатели языка оставили программисту на его усмотрение.
Таким образом, исключение RuntimeException является не проверяемым и выбрасывается во время выполнения Java кода, и его дочерние исключения также являются не проверяемыми.
Это исключение IndexOutOfBoundsException – выбрасывается, когда индекс некоторого элемента в структуре данных не попадает в диапазон имеющихся индексов.
Исключение NullPointerException – выбрасывается, когда ссылка на объект, к которому вы обращаетесь, хранит null.
Исключение ClassCastException – это ошибка приведения типов.
И исключение ArithmeticException – выбрасывается, когда выполняются недопустимые арифметические операции, например, деление на ноль.
Исключение Error также является не проверяемым, которое показывает серьезные проблемы возникающие во время выполнения приложения. Исключение Error сигнализирует о ненормальном ходе выполнения программы, т.е. о каких-то критических проблемах.
