On 5 October 2011 02:05, Phil Steitz <phil.ste...@gmail.com> wrote: > On 10/4/11 4:26 PM, Gilles Sadowski wrote: >>>> I have been leaving the standard exception advertisements alone as I >>>> s/MathRuntimeException.createXxException/new MathXxException, but I >>>> notice others are changing the @throws to declare the >>>> MathXxException. We should probably be consistent. I don't know if >>>> it really makes any difference. I see a pro and a con for each >>>> approach: >>>> >>>> advertise MathXxx >>> +1 >>> Rationale: CM documents what it does. >>> >>>> pro: users can catch / differentiate math-generated exceptions from >>>> other standard exceptions of the same type up the stack >>>> con: users may needlessly scratch heads or check javadoc to make >>>> sure that, e.g. MathIAE *is* IAE, so they can skip the import and >>>> catch IAE. >> I don't understand the worry; either they read the Javadoc of a method and >> can readily click on the link to see the exception Javadoc and its whole >> hierarchy, or they read the source code and can open the corresponding Java >> file to obtain the same information. > > The more users have to think about your code when using it, the less > likely they are to use it and the less happy they will be when using > it. Users should never have to look at the source to understand the > API. This is one of the reasons that it is better to favor standard > exceptions. Advertising IAE is clear and simple - no chasing down > javadoc, no import, no thought required.. Advertising MathIAE, > which is noting more than an IAE with localized message, adds > unnecessary complexity for the user, IMO.
Which is why I suggested documenting that MathIAE is IAE in the throws clause - AFAICT that would be the best of both worlds. > Phil >> >>>> advertise Xxx >>> -1 >>> >>>> pro: follows "favor standard exceptions" practice and avoids need to >>>> head scratch or import (also the ones that I am talking about are >>>> really just the standard exceptions with localized >>>> message-generation capability) >> An exception instance should convey the nature of the failure without having >> a human read the error message string. >> >>>> con: users don't know they can catch the more specific exception >>>> >> Gilles >> >> --------------------------------------------------------------------- >> 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
