I can give some feedback based on JSR-310. 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). 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. 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. In general though, the main advice is to keep it simple. People rarely use exception hierarchies. Mostly they want the message to be readable to diagnose the problem in a stack trace. 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. Similarly, look at the standard JDK executor framework (ExecutionException) to understand the necessity to wrap callbacks. Stephen On 1 February 2011 00:38, Phil Steitz <phil.ste...@gmail.com> wrote: > We are in process of redesigning our exceptions hierarchy in [math] > and we could use some input / perspective from other Commons > community members. Thanks in advance for your feedback and perspective. > > The most recent attempt at agreeing on design principles is [1] and > I have tried to document the points of agreement in a section that I > just added to the [math] Developer's Guide [2] (it will take a few > hours for this to make it to the live site. The source xdoc is in > trunk/src/site/xdoc/developers.xml) > > The JIRA issue [3] referenced in [1] calls out a specific point on > which we are trying to gain consensus in a specific example. > > The currently defined exceptions in [math] can be found in the > top-level package and .exceptions. Those in the top-level have at > this point been deprecated. > > Thanks! > > Phil > > [1] http://markmail.org/message/csgdloie6uv33yua > [2] http://commons.apache.org/math/developers.html > [3] https://issues.apache.org/jira/browse/MATH-487 > > --------------------------------------------------------------------- > 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
