Home/ Questions/Q 6785571
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-26T17:08:35+00:00

How liberally should I use @throws in my javadoc, or any API? For instance,

  • 0

How liberally should I use @throws in my javadoc, or any API? For instance, if I have:

LDAPException
NullPointerException
IllegalArgumentException
Exception

Should I be using @throws for each one, or should I just say @throws Exception?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    Ideally, the javadoc @throws clauses should be a superset of your actual method throws clause.

    For example, if your method throws IOException, you may not only have a @throws IOException to explain situations when a generic I/O error occurs, but also @throws FileNotFoundException (a subclass of IOException) to talk about why that may happen.

    Likewise, you may document @throws NullPointerException to state when this may occur, even if you don’t declare throws NullPointerException, since it’s an unchecked exception and does not need to be (and generally is not) written in the method signature.

    Should you @throws Exception? No, but, more generally you should not throws Exception. That’s a different discussion. But as a result, no, it would not be good to repeat this sort of bad practice in javadoc. What would it talk about — the different exceptions that can occur? then why not document them one by one with @throws anyway?

    • 0