Have read the following from guidelines to writing Javadoc comments.
A @throws tag should be included for any checked exceptions (declared in the throws clause), as illustrated below, and also for any unchecked exceptions that the caller might reasonably want to catch, with the exception of NullPointerException.
from the following web-site
Does this mean, for example, if one is passing objects to methods, e.g., that if they specify in their Javadoc documentation, say in the overview.html, that they never tested for null objects passed into methods, that is the responsibility of the tester user to recognise this and accept it will raise a RuntimeException? This of course would be different to an IllegalArgumentsException, where, for example, none of the fields of the data array could be null, say regarding a business rule.
You may wonder why I'm asking this question, just wondering could I get away without testing for null objects passed into methods. or and whether it's acceptable.
In all my javadoc comments I never documented (or even mentioned) a NullPointerException, but of course I developed my code in such a way that a NullPointerException can't occur. Never!
From my create-method for example (just a snippet):
So if the caller passes a null value an IllegalArgumentException will be thrown and so I'm also guaranteed that when the actual code of the create method is executed I don't have to clutter my code with tests to see if data is null. And of course I did also a lot of other tests to validate the parameter (length of the array, contents of the array,...).
The main advantage of this approach (in my opinion) is that these tests occur at the start of your method. If these tests are passed successfully you know you are working with a valid parameter and you don't have to provide any checks in your actual code which simplifies your code a lot. Otherwise an exception is thrown and the caller of your method gets a clear message "the array must not be null" instead of a NullPointerException or ArrayIndexOutOfBoundsException (when the array has just 4 elements when the method expects 6).
Roel, are you saying that in your opinion is a good practice to check a parameter passed to a method for null and throw an IllegalArgumentException in case of null before start using it? Or just for this project?
Here is a situation:
I don't know how you can deal with this situation. I think that in this specific case you can't do anything then letting a NullPointerException being thrown or check for null in the calling method. How did you validate the recNo parameter?
are you saying that in your opinion is a good practice to check a parameter passed to a method for null and throw an IllegalArgumentException in case of null before start using it?
Yes, that's my point. you should validate the parameters before using them and throw an IAE with a clear message when they are not what you expected.
The example code you gave has nothing to do with parameter checking. It will throw a NullPointerException due to unboxing at line 6 of your code, so it's just a bad example (to illustrate this point).
Another example illustrating my point, could be:
Of course if null is a valid value for the parameter that you pass, you won't do the check. That should be obvious
If you expect a String-array to be not-null, to be of the same size as the number of columns in the database, contains no null-values,... these checks you should provide at the beginning of your method to check if your parameter is valid. And you don't have to add checks for null or checks for correct size in the actual code of your method. Your code will become simpler and easier to maintain. (my javadoc comments clearly tell each situation when an IAE will be thrown)
Of course that is just my opinion about this issue and it is not only for this assignment, but also when you are developing on your job (and certainly if you are developing a framework/API that will be used by other developers).
So if the caller passes a null value an IllegalArgumentException will be thrown
I think that a NullPointerException should be thrown with a specified detailed message - instead of an IllegalArgumentException.
The API spec for NullPointerException seems to indicate that this is a better choice.
Several classes in the Java API also behave like this. For instance a List will throw a NullPointerException is null is being added to the List, and it throws IllegalArgumentException for different reasons.
What do you guys think?
As an aside, I have also created an exception throwing utility for just this purpose, the code is :