Should I declare IllegalArgumentException in my method declaration
Hi,
I have a setter method which throws an IllegalArgumentException which is of type RuntimeException... It means that I need not declare it in my method declaration, but I should explicity describe in Javadoc.
Is it a good practice to declare it in throws clause just to make it more readable? or is it superfluous and unnecessary because I am going to describe it in Javadoc anyway?
I mean....
/**
* @throws IllegalArgumentException
*
*/
publicvoid setterMethod(){
}
vs
/**
* @throws IllegalArgumentException
*
*/
publicvoid setterMethod()throws IllegalArgumentException{
}
Thank you,
Srikanth
[1052 byte] By [
sri1025a] at [2007-10-3 6:40:05]
I would as they are part of your interface. See: http://webcem01.cem.itesm.mx:8005/web/java/tutorial/essential/exceptions/runtime.html
> I have a setter method which throws an
> IllegalArgumentException which is of type
> RuntimeException... It means that I need not declare
> it in my method declaration, but I should explicity
> describe in Javadoc.
If you conclude that it is important that the other programmers know in which situation your method throws an IllegalArgumentException then go ahead and describe it in javadoc. If you think that it's not important, or it's not necessary, you don't need to describe it. But in general, the unchecked exception IllegalArgumentException, if it is used according to its purposes, deserves a javadoc description. Although I think you are not using this exception appropriately, because your method doesn't even have a parameter! I hope you are showing just an example, just to support your question.
> Is it a good practice to declare it in throws clause
> just to make it more readable? or is it superfluous
> and unnecessary because I am going to describe it in
> Javadoc anyway?
No! It does not make it more readable. IllegalArgumentException is an unchecked exception, so you have to take advantage of this "uncheackability", that is, the advantage of not being needed to declare that the method throws it. In any case, you shouldn't declare the throws clause for any kind of unchecked exception. A description in javadoc is enough. But I see that you're just saying that the method can throw IllegalArgumentException, in the javadoc. Why don't you give more details? It is a good practice. See below an example:
/**
* @throws IllegalArgumentException if the parameter name passed is null,
* or if it is equal to "".
*/
public void setterMethod(String name) {
}
Yes,I was showing just an example to support my question. And you are right that I should give some more detail in Javadoc as to why and when it throws the exception.Thank you!
I would put it in the javadocs, but not in the method declaration. Adding it to the javadocs is useful for the programmer using it, but adding it to the throws clause does nothing additional.
runtimeexceptions are what is generally called bugs, it should be avoided. your method should not declare to throw any runtimeexceptions. you are allowed to throw checked exceptions only.
> runtimeexceptions are what is generally called bugs,
Correct.
> it should be avoided.
If you mean you should write your code without bugs, then, yes, that's the goal.
> your method should not declare
> to throw any runtimeexceptions.
There's nothing wrong with doing so, but it's rather pointless.
> you are allowed to
> throw checked exceptions only.
Wrong.
@OP and anyone else who's trying to learn something here: Ignore daFei. He is a troll who has been polluting these forums with nonsense for years.
> you are allowed to throw checked exceptions only.Stop trolling, daFei.~
> > your method should not declare
> > to throw any runtimeexceptions.
>
> There's nothing wrong with doing so, but it's rather
> pointless.
I don't necessarily agree that it's pointless. Take, for example, an IllegalArgumentException. Declaring it makes it immediately obvious upon examining the source code that there are conditions that apply to the arguments used when calling the method. Furthemore, with my IDE, there's a small bit of automation provided for javadocs when it comes to declared Exceptions. And IMHO, something like potential IllegalArgumentExceptions demand a javadoc explanation.
What problems do you see with this approach?
~
> > > your method should not declare
> > > to throw any runtimeexceptions.
> >
> > There's nothing wrong with doing so, but it's
> rather
> > pointless.
>
> I don't necessarily agree that it's pointless. Take,
> for example, an IllegalArgumentException. Declaring
> it makes it immediately obvious upon examining the
> source code that there are conditions that apply to
> the arguments used when calling the method.
For that, I'd just put it in the javadocs. That way it's in the source and in the docs. Adding the declaration beyond that is just clutter, IMHO.
> Furthemore, with my IDE, there's a small bit of
> automation provided for javadocs when it comes to
> declared Exceptions.
Okay, good point there. Still, I think I'd rather type it in the javadocs and keep the clutter out of the throws clause.
> And IMHO, something like
> potential IllegalArgumentExceptions demand a javadoc
> explanation.
Yup.
> What problems do you see with this approach?
Clutter and redundancy. Not major problems, just personal preference.
> Clutter and redundancy. Not major problems, just> personal preference.10-4, thanks.~
> I don't necessarily agree that it's pointless. Take,
> for example, an IllegalArgumentException. Declaring
> it makes it immediately obvious upon examining the
> source code that there are conditions that apply to
> the arguments used when calling the method.
> Furthemore, with my IDE, there's a small bit of
> automation provided for javadocs when it comes to
> declared Exceptions. And IMHO, something like
> potential IllegalArgumentExceptions demand a javadoc
> explanation.
This is what made me to ask this question. Because the API that I am writing may change in future before other programmers start to use it. Till I test out a few examples myself and till the API gets into a good shape, I decided to postpone writing the javadocs.
So I was declaring all the runtime exceptions in my method body so that I can use my IDE to generate the @throws and another reason is I won't forget it to document.
But just when I was writing for 3 to 4 classes, I felt a little uncomfortable declaring them just for the sake of IDE java doc generation. But now I decided to remove the throws clause once I finish my javadocs...
