----- "Stephen Colebourne" <scolebou...@joda.org> a écrit :
> 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.
So users who want to extract data put in their code statements along
the line of : if (e instanceof subClassException) { ... } ?
>
> 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.
The localization part and the hierarchy are two completely different topics.
>
> In general, exceptions are for two purposes - info on failure and to
> trap for retry.
Yes.
>
> Info on failure simply needs a good message in English.
No. Some people do not read English at all. In many systems a strong
requirement is that every message users can see must be localizable.
Localizing a message that has variable parts (numerical values,
strings, booleans) after the message has been built on a top level layer
is impossible.
> 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.
Agreed.
>
> In general though, the main advice is to keep it simple. People
> rarely
> use exception hierarchies. Mostly they want the message to be
> readable
Yes.
> to diagnose the problem in a stack trace.
No. End users are not always developers, or they may have no access to the
source code, or they may not know the architecture of the applications,
they may even not known Commons Math is used behind the scenes in a low
level layer. Stack trace are not for users and we should not rely on them.
>
> 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.
Yes.
>
> Similarly, look at the standard JDK executor framework
> (ExecutionException) to understand the necessity to wrap callbacks.
Thanks, we'll have a look at it.
Luc
>
> 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
