Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX: Exceptions and JavaDoc

 
Javini Javono
Ranch Hand
Posts: 286
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
Given Sun's Data class which extends DBMain,
this class will be encapsulated within a
new class called DataFace; and, DataFace
will through all appropriate exceptions:
such as IOException, IllegalArgumentException,
or what have you.
So, the above are the specifics, but my question
is actually more general in nature. When I design
a new class, and I don't want to hamper the class
(or interface) by restricting what exceptions it
may throw in the future, how do you square this method:
public class DataFace extends Object {
public long someReadMethod(...) throws Exception {}
}
with JavaDoc?
That is, can I simply say in JavaDoc that Exception will
be thrown and then comment it like this:
"At this time the following checked exceptions may be
thrown: IOException, IllegalArgumentException. As it
is always possible that for a future, unanticipated
update the database file may be moved to another server
thus introducing a whole host of new exceptions, it was
deemed necessary not to restrict the exceptions that could
potentially be thrown by this method."
In short, if you create a public interface, and the possibility
exists that at some future date the exceptions that this method
may throw may grow, can I deal with this situation by simply
stating that my method throws Exception; that is, is this
against the way Sun expected exceptions to be documented (not
only with respect to this assignment, but with respect to
normal, work-related production software)?
Thanks,
Javini Javono
 
Bill Robertson
Ranch Hand
Posts: 234
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey Javini,
IMO, what you have is a rather confusing design. Why ?
1. First off, exceptions are part of the signature of a method. So if more exceptions come along, yes your method may brake without "throws Exception",
but that could be a good thing because you get notified of the changes automatically. Changes that you may not agree with or may have a negative
impact on what your trying to accomplish.
2. Also the signature of a method is like a contract. It some what gives away what the method can do and what it's used for. If you just have "throws Exception" you are not telling other users very much about what the method really does.
3. And most importantly, how are those calling your method going to handle
the exceptions properly? Do you expect them to trace through the methods code to determine the exact exceptions it throws so they can catch them and
respond properly. You do not want this, which is why we put the exceptions that a method throws in its signature in the first place.
just my simple two cents worth
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Javini,
I agree with Bill - you really should declare the explicit exceptions that may be thrown from each method.
If you simply declare that your methods can throw Exception, then
  • If there is some exception that your method should be catching and handling, but you forget to put it in, then you will not receive any notification when you compile: the compiler will just assume you know what you are doing.
    For example, you may want to catch the RecordNotFoundException within your find() method, but if you forget to put it in, then all of a sudden your clients will start getting RecordNotFoundExceptions whenever a record is deleted .
  • Clients must read your API documentation and hope that it is 100% correct and up to date in order to use your methods (and we all know that documentation is always up to date :roll: ). They cannot use any code generators, and they cannot rely on the compiler warning them if they forget to catch a particular exception.
  • The client code becomes far more messy. Instead of having catch blocks specific to the exception that may be thrown, they have to have a very generic catch block.
    Instead of:


  • You get:

  • Whenever you ship a new version of your code, the clients must manually read through every line of code they wrote that calls one of your methods and look up the appropriate API to ensure that you have not added some exception that they now need to handle.


  • Also, look to the Java SDK API - you should see that the Sun developers never throw Exception. They always throw a specific exception.
    Regards, Andrew
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic