Hi. On Tue, Feb 01, 2011 at 11:38:04AM +0000, Stephen Colebourne wrote: > I can give some feedback based on JSR-310.
Thank you for sharing ideas. > I have a small hierarchy of exceptions that attempts to capture some > key problems that may occur. The problem I found was that as I > refactored code, the exceptions listed in Javadoc quickly became > inaccurate. As a result, I've started converting many exceptions to > the parent CalendricalException. If a method returns a subclasses of > CalEx then thats fine and provides more info. But documenting it as > returning the subclass is way too much work for limited gain. > > For [math], simply documenting MathException is sufficient. > MathRuntimeException, is unecessary as a name when all exceptions are > runtime (the correct decision). Agreed. > More generally, an obsession with having every piece of exception data > available via a variable is generally unhelpful. It simply leads to > large unmaintainable hierarchies and arguments like this one. It is > very rare to need the data. [math] is suffering because of localizing > exception, which IMO is a big mistake and the cause of a lot of the > issues. There are 2 independent issues here. As a low-level component, CM cannot assume how it's failure are going to be reported. Having exception data programmatically acessible allows the application developers to format the failure message as they wish. On the localization issue, I was in agreement with your view. Unfortunately, it seemed to have been a requirement from one of the big users of CM. There was a long thread where we had been discussing all this: http://markmail.org/message/emh7nr5nuultgkx4 > In general, exceptions are for two purposes - info on failure and to > trap for retry. > > Info on failure simply needs a good message in English. No data is > required, although important (certainly not all!) pieces might be > captured. > > Trap for retry errors should be rare if present at all. I would much > prefer to see a proper result object which everyone is forced to check > to describe the success or failure of something that might be retried. My conviction is that a true "retry" will never happen in CM. > In general though, the main advice is to keep it simple. People rarely > use exception hierarchies. Although you said that it saved your day to have a parent exception ;-). > Mostly they want the message to be readable > to diagnose the problem in a stack trace. For me too, it's the most common use. > Finally, use the standard exceptions and patterns. IllegalArgumentEx > for example (which won't extend from MathEx, so does require separate > documentation). As in the guide, IllArgEx is for preconditions > mentioned in Javadoc or reasonably related to them, not general > calculation issues. Here we (in CM) arrived to the consensus that it would be simpler to have all our exceptions rooted at "RuntimeException". Unfortunately, that makes us depart from the other standard exceptions. For example, we created a "MathIllegalArgumentException" that is not a subclass of the standard "IllegalArgumentException" although it is semantically equivalent. This decision was indeed partly due to the complication induced by the localization "framework" (to avoid code duplication). > Similarly, look at the standard JDK executor framework > (ExecutionException) to understand the necessity to wrap callbacks. Fortunately, we don't have to deal with such complex code flow. Best regards, Gilles --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
