Должно ли непроверенное исключение быть описано в JavaDoc? - PullRequest
Новая
       10

Должно ли непроверенное исключение быть описано в JavaDoc?

0 голосов
/ 23 мая 2018

У меня есть следующий код: 

public User getUserById(Long id) {
checkUserExists(id);
return repo.findOne(id);
}

private void checkUserExists(Long id) {
    if (id == null || !repo.exists(id)) {
        throw new NoUserFoundException("No User exists with id: " +id);
    }
}

Согласно оракулу:

"Не проверенные исключения не нужно объявлять в предложении метода или конструктора throws, если они могутбыть брошенным выполнением метода или конструктора и распространяться за пределы границ метода или конструктора. "

Должен ли я в любом случае описывать исключение в JavaDoc (без предложения @throws, но толькоописать?) Как лучше всего описать такое непроверенное исключение в JavaDoc?

Заранее спасибо!

1 Ответ

0 голосов
/ 23 мая 2018

Вы пишете Javadoc для пользователя вашего метода.Если для этого пользователя полезно знать, что оно может вызвать исключение, запишите это!

В вашем случае, кажется, что пользователю действительно полезно знать, что NoUserFoundException выбрасывается, если пользовательне найден.

В других случаях это менее полезно.Например, во многих случаях тот факт, что NullPointerException выбрасывается, если параметр имеет значение NULL, не задокументирован в Javadoc, потому что часто как-то подразумевается, что параметр не может быть NULL.

Кстати, Oracleговорить о классе throws, который появляется после объявления метода, а не о Javadoc.Если вы решили задокументировать непроверенное исключение, имеет смысл использовать предложение @throws.

...