is @throws useless?
Both Bloch and Sun recommend that both checked and unchecked exceptions be documented with the @throws javaodc tag.
I have just spent a week editing javaodc, and I have come to a distinct feeling that @throws adds little or no value.
Checked exceptions - these are already processed adequately by the javadoc tool. There is no need to repeat this information in a @throws tag.
Unchecked exceptions - these always represent programming errors. (Bloch: "Use checked exceptions for recoverable conditions and run-time exceptions for programming errors"). Since when is the caller expected to recover from programming errors? In the case of a param having certain conditions, those conditions should be stated *once* in the @param tag, and not repeated in a related @throws tag. In short, unchecked exceptions do not form part of the contract - rather, they indicate that the contract is broken - and should *never* appear in the javadoc.
What do you think? "Out to lunch" or "Right on, brother!" ?
[1025 byte] By [
johanleya] at [2007-9-28 16:37:18]
In my opinion, the @throws tag should try to tell you why the exception was thrown, so that the caller can attempt appropriate correction.
For example, in SQL processing you'll typically go through several steps: create the PreparedStatement, apply parameters, execute, and retrieve results. The meaning of a java.sql.SQLException may be very different depending on which step you're doing, so if you divide the steps between two or more procedures, it's helpful to document the reasons why the exception might be thrown.
Of course, much of the time you'll have no idea what's causing the exception, or no good way to correct the situation. In these cases, I'll agree that @throws has little value.
SQLException is probably a good example of when you don't want to do it as well.
How many possible ways can DriverManager.getConnection() fail? There are probably hundreds if not thousands. The java docs should not document those cases.
If the exception is generated based on a very specific and limited number of circumstances then document it. Otherwise don't.
I believe that the comment about runtime exceptions due to programming errors refers to errors in the the caller's code. I prefer to use the (very!) broad distinction between "my fault" and "your fault" to distinguish between checked and runtime exceptions.
The need for the @throws tag is clear if you consider the purpose of Javadoc. It is not the job of Javadoc to rewrite an API in "plain English" (or whatever your intended language). Javadoc is only really useful if it adds value to the API and goes beyond simply rewriting the method signatures.
Of course a well-named, well-designed API doesn't need much in the way of explanation. However, it's in the area of preconditions, parameter constraints and exceptional circumstances that even a well-written API will really benefit from Javadoc.
You're right that the @param tag should cover off most constraints and these should not be repeated in the @throws tag. However, the @throws tag should indicate a means of determining which constraint has been violated. There are, of course, cases where the contract may be broken outside the set of parameters being passed and thus the @throws tag provides one means of indicating why a method may have failed for reasons other than illegal arguments (eg, IllegalStateException thrown if initialise hasn't yet been called).
You're right again that checked exceptions are usually handled sufficiently simply by noting their existence as the client may be unable to do much about them. Needless to say, in some cases there'll be something worth reminding the user about should they get an exception of this type.
Remember, it's documentation, not simply an explanation of what the Java signatures mean - the worst type of documentation is that from which you can't find what you want quickly (and that means a lot of referring to other methods/classes/etc). It's probably the case that Javadoc should be written by a technical author, not just the developer of the code (but sadly that's not gonna happen in most companies).
