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

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

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

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

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

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

«Магия утра». Хэл Элрод | Саммари


Читать еще…

Понравилась статья? Поделиться с друзьями: