Hi Gilles, Le 13/01/2012 11:59, Gilles Sadowski a écrit : > On Fri, Jan 13, 2012 at 07:04:10AM -0000, celes...@apache.org wrote: >> Author: celestin >> Date: Fri Jan 13 07:04:10 2012 >> New Revision: 1230906 >> >> URL: http://svn.apache.org/viewvc?rev=1230906&view=rev >> Log: >> Javadoc >> Made sure that exceptions are documented in both javadoc and method >> signatures. > > This is not good style: Unchecked exceptions in method signatures do not > offer any guarantee to the caller;
This is still better than nothing. Not giving any hints to user about exceptions that may be thrown is even worse style IMHO. > not that only those exceptions will be > thrown and not even that these exceptions can actually be thrown. > Thus, it brings a level of redundancy (between Javadoc and signatures) that > must be kept in sync manually; this is a burden and has no benefit.[1] > Unchecked exceptions must be documented in Javadoc, but should not appear in > method signatures (at least, not systematically). > > > Best regards, > Gilles > > [1] Luc likes to have the exception in the signatures because, as a CM > developer, he can (temporarily) change the definition of an exception > (to make it "checked") and then the compiler will tell whether some > (user) code is prepared to handle that exception. But who else is going > to do that? I used to do that when we still had a single root hierarchy. Changing the root temporarily to checked was a simple and efficient way to make sure javadoc was OK. Now we have removed the single root and this has become a nightmare to maintain as every single exception has to be temporarily changed to checked in order to do this bookkeeping. This is impossible to do. As Throwable, Exception and RuntimeException are all classes and not interfaces, we can even not declare some intermediate MathThrowable interface that would extend RuntimeException in production distribution and could be changed to extend Exception in developers works spaces to ensure javadoc and throws statements are up to date. I sincerely regret this. Luc > >> [...] > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
