Для каждого метода документируйте все инициируемые исключения

Описание инициируемых методом исключений составляет важную часть документации, которая необходима для правильного применения метода. Поэтому крайне важ­но, чтобы вы уделили время тщательному описанию всех исключений, инициируемых каждым методом.

Обрабатываемые исключения всегда декларируйте по отдельности с по­мощью тега @throws (Javadoc), четко описывайте условия, при которых каждое из них инициируется. Не пытайтесь сократить описание, объявляя о том, что метод инициирует некий суперкласс исключений, вместо того, чтобы декларировать несколь­ко классов возможных исключений. Например, никогда не объявляйте, что метод инициирует исключение Exception или, что еще хуже, исключение Throwable. Помимо того, что такая формулировка не дает программисту никакой информации о том, какие исключения могут быть инициированы данным методом, она значительно затрудняет работу с методом, поскольку надежно перекрывает любое другое исключение, которое может быть инициировано в этом же месте.

Хотя язык Java не требует, чтобы программисты декларировали необрабатывае­мые исключения, которые могут быть инициированы данным методом, имеет смысл документировать их столь же тщательно, как и обрабатываемые исключения. Необра­батываемые исключения обычно представляют ошибки программирования (статья 40), ознакомление программиста со всеми этими ошибками может помочь ему избежать их. Хорошо составленный перечень необрабатываемых исключений, которые может инициировать метод, фактически описывает предусловия для его успешного выполне­ния. Важно, чтобы в документации к каждому методу были описаны его предусловия, а описание необрабатываемых исключений как раз и является наилучшим способом выполнения этого требования.

Особенно важно, чтобы для методов интерфейса были описаны необрабаты­ваемые исключения, которые могут быть ими инициированы. Т акая документация 'является частью основных соглашениu для интерфейса и обеспечивает единообразное поведение различных его реализаций.

Для описания каждого необрабатываемого исключения, которое может быть инициировано методом, используйте тег @throws (Javadoc), однако не нужно с помощью ключевого слова throws включать необрабатываемые исключения в декларацию метода. Программист, пользующийся вашим API, должен знать, какие из исключений обрабатываются, а какие - нет, поскольку в первом и втором случаях на него возлагается различная ответственность. Наличие описания, соответствующего тегу @throws, и отсутствие заголовка к методу, соответствующего декларации throws, создает мощный визуальный сигнал, помогающий программисту отличить обрабатыва­емые исключения от необрабатываемых.

 

 

170

 

 

Следует отметить, что документирование всех необрабатываемых исключений, которые могут быть инициированы каждым методом,- это идеал, который не всегда достижим в реальности. Когда про изводится пересмотр класса и предоставляемый пользователю метод меняется так, что начинает инициировать новые необрабатывае­мые исключения,' это не является нарушением совместимости ни на уровне исходных текстов, ни на уровне байт-кода. Предположим, некий класс вызывает метод из другого класса, написанного независимо. Авторы первого класса могут тщательно документировать все необрабатываемые исключения, инициируемые каждым методом. Однако если второй класс был изменен так, что теперь он инициирует дополнительные необрабатываемые исключения, первый класс (не претерпевший изменений) тоже будет передавать эти новые необрабатываемые исключения, хотя он их и не декларировал.

Если одно и то же исключение по одной и то же причине инициируется несколькими методами, его описание можно поместить в общий комментарий к документации для всего класса, а не описывать его отдельно для каждого метода. Примером такого рода является исключение NullPointerException. Прекрасно было бы в комментарии к классу сказать "все методы этого класса инициируют исключение NullPointerException, если с каким-либо параметром была передана нулевая ссылка на объект" или другие слова с тем же смыслом.

 

⇐ Предыдущая31323334353637383940Следующая ⇒

Поделиться: