Re: On throwing exceptions on method arguments
Jacob wrote:
Eric Sosman wrote:
The Javadoc should probably describe the exception thrown,
or at the very least describe the valid parameter values. For
brevity's sake you might just say "@see doSomething". Some IDE's
may whine when you have a @throws for something that's not in the
method signature, but remember: The IDE is supposed to be your
servant, not your master.
Problem is that the "something" you refer to may be private.
You described it as public in the original post. In any event,
using @see is a convenience, not a necessity. If you've got
forty-two public convenience methods all wrapping a single private
method, you could document the contract in one of them (typically
the "most general") and use @see in the others, or you could
document them all individually (which might not be all that
duplicative, since the forty-two wrappers presumably have forty-
two different sets of parameters to be documented).
And should my method be responsible for declaring throws clauses
for anything that my sub-methods may throw? I don't think this
scale very well.
For checked exceptions it's a necessity -- people have debated
whether that's Good or Bad, but either way it's Java and you're
stuck with it. For unchecked exceptions it's a matter of taste,
or of trying to guess the frame of mind of the person reading the
documentation.
The problem is that the particular method doesn't throw anything
at all, but I still need to communicate the valid parameter ranges
to my client.
Then go ahead and document them. There is no rule (no Java rule,
anyhow) saying that every requirement must be enforced by a throw.
It's very often a good idea to do so, but if you've got a situation
where you require that a parameter be a prime number you might just
choose to say "The parameter {@code foobar} must be prime; if it is
composite, SAFUYOYO."
--
Eric.Sosman@sun.com