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. 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
