CODEWITHSUNDEEP
javajavadoc
robonerd
robonerd

Reputation: 198

Best practices for documenting exception which caused by unknown arguments

This is more of a best practices question. I hope that it's okay to ask this question here. I am creating an interface that will be used as part of our API. I have a method called getSomeObject() which has a complected logic behind the scenes and returns SomeObject. Behind the scenes I am calling the method which throws IllegalArgumentException, so there is a possibility that my getSomeObject() method may throw this exception. The problem I have is that the user of the API is not familiar with inner workings of the API and wouldn't understand why the exception was thrown. Since the argument is created inside my method and the user doesn't even know that this argument exists. I was trying to document it, but the reason for this exception would confuse the user of the API. So my question is, what is the best way to go about the situation like this? What is the correct way to document this exception?

Upvotes: 1

Views: 110

Answers (2)

Rohit
Rohit

Reputation: 583

When you say that there is a possibility of your internal code throwing IllegalArgumentException , how are you handling it ?
Is it caused by faulty input by the user ?
if not then you should catch it and handle it and if still you have to throw it it has to be translated into an exception that the user can make sense
Or is the chance of that happening unlikely and is purely theoretical?
If this is a valid exception scenario that the user should handle you should throw an appropriate checked exception and declare it in your interface

Upvotes: 1

assylias
assylias

Reputation: 328619

Throwing an IllegalArgumentException from a method that does not take any arguments is indeed quite confusing.

I suppose you get that exception if something outside of getSomeObject is not properly defined. So you could maybe throw an IllegalStateException, and document it with an explanation in your javadoc:

@throws IllegalStateException If member variable xyz is not initialised.  
                              This can happen if method `init()` has not been   
                              called before `getSomeObject`.

Upvotes: 7

Related Questions