Чи повинні методи, які кидають RuntimeException, вказувати це в підписі методу?

Наприклад, багато методів у фреймворках / JDK можуть кидати

java.lang.SecurityException 

але це не зазначено в підписі методу (оскільки це практика, яка зазвичай зарезервована для перевірених винятків). Я хочу заперечити, що оголошення RuntimeExceptions у методі sigs має багато переваг (подібних до перевірки статичного типу, наприклад). Я п'яний чи інакше?

Я б не оголошував у підписі неперевірений виняток, оскільки це вводить в оману користувача цього API. Більше не очевидно, чи потрібно чітко обробляти виняток.

Оголошення цього в javadoc - кращий підхід, оскільки він дозволяє комусь з цим впоратися, якщо вони вважають це необхідним, але знаючи, що можуть ігнорувати його, якщо хочуть. Це робить чітким розділення між перевіреним та неперевіреним.

З підручника з Oracle Java :

"Якщо так добре задокументувати API методу, включаючи винятки, які він може створити, чому б не вказати також винятки під час виконання?" Винятки під час виконання представляють проблеми, які є результатом проблеми програмування, і тому не можна розумно очікувати, що код клієнта API відновлюється від них або обробляє їх будь-яким чином. До таких проблем належать арифметичні винятки, такі як ділення на нуль; винятки покажчиків, такі як спроба отримати доступ до об'єкта через нульове посилання; та індексування винятків, таких як спроба отримати доступ до елемента масиву за допомогою занадто великого або замалого індексу.

Винятки під час виконання можуть траплятися в будь-якому місці програми, а в типовому варіанті їх може бути дуже багато. Додавання винятків часу виконання в кожному оголошенні методу зменшить ясність програми.

Погляньте на javadoc для колекції # add

Згадано цілу низку неперевірених винятків:

Throws:
UnsupportedOperationException - add is not supported by this collection.
ClassCastException - class of the specified element prevents it from being added to this collection.
NullPointerException - if the specified element is null and this collection does not support null elements.
IllegalArgumentException - some aspect of this element prevents it from being added to this collection.

Якщо у вас є терпіння, я рекомендую ретельно задокументувати можливі винятки, викликані вашими методами, таким чином. Певним чином, це навіть важливіше робити це для неперевірених винятків, оскільки перевірені винятки дещо самодокументуються (компілятор змушує код виклику їх визнати).

З моєї точки зору, краще оголосити винятки під час виконання принаймні в javadoc для методу. Заявлення про це в підписі робить ще більш очевидним, що може статися, коли щось піде не так. Це моя головна причина для пропозиції надати цю інформацію.

FYI: з плином часу (тепер у 2017 році) я зараз нахиляюсь набагато більше до документування їх лише у javadoc та, наскільки це можливо, уникаю перевірених винятків.

На мій погляд, неперевірені винятки ніколи не повинні оголошуватися в підписі методу, оскільки це суперечить їх природі.

Якщо, однак, метод, швидше за все, видасть деякі неперевірені винятки, зазначивши ймовірні обставини в @throws в Javadoc, може бути корисним для інших, хто використовує метод, щоб зрозуміти, що може піти не так. Це корисно лише для винятків, з якими, мабуть, зможуть обробляти абоненти (наприклад, NPE через поганий вхід тощо)

Якщо ви пишете api для використання іншими, тоді є достатньо підстав для явного документування вашого наміру в api, і немає недоліків у оголошенні RuntimeExceptions у підписі методу.

Це пов’язано з дискусією щодо перевірених винятків . Більшість погодиться, що винятки не повинні оголошуватися в підписах методів.

Існує також дискусія щодо того, як слід використовувати винятки під час виконання. Я погоджуюсь з одним плакатом, що винятки під час виконання повинні позначати помилку програмування або фатальний стан. Отже, немає великої заслуги в тому, щоб оголосити їх у підписі. Кожен метод може потенційно через один.