commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gilles (JIRA)" <>
Subject [jira] Commented: (MATH-361) Localization and Error Handling
Date Fri, 25 Jun 2010 14:15:50 GMT


Gilles commented on MATH-361:

What I don't agree with is the fact error messages are for the set of users that must read
the javadoc. Error messages are for end users, some of them not even knowing commons-math
is used in an application they use. They don't read the javadoc, they don't develop the application.
But when a statistician tries to set up a gamma distribution and get a message about alpha
being negative, he will better understand what his input error was than if a generic "negative
parameter" message was displayed.

At best, there is lot of confusion (about exception usage) in these statements. I guess that
part of it stems from the fact that you are CM-developer, CM-user, CM-service provider, CM-based
application developer, CM-based application user, ...

First, the error messages are indeed for the user of CM, that is the _programmer_ that uses
the low-level CM library to build a high-level application. If he lets the CM exception propagates
upwards to _his_ users, that is sloppy design.
To be more precise, in the "statistician" example, what do you mean by "tries to set up a
gamma distribution"? The answer is:

* either he is coding something himself (thus he _is_ the application programmer, and must
read the Javadoc, etc.)
* or he is using a software that will call CM methods. The programmer of that software must
have read the Javadoc (where it is indicated that "alpha" must be positive) and if he called
"setAlpha" with a negative argument anyways, that is a _bug_ in his program.

The Java language designers provided several mechanisms for exception handling but not always
clearly promoted tried and true best practices. Fortunately some people did. Do you have access
to a copy of Joshua Bloch's _"Effective Java"_? I found that the section on "Exception" is
enlightening; especially, "items" 40, 41, 43, 45 address all we have been arguing about.

The bottom line is:
[...] don't consider messages are for developers using directly commons math.
The vast majority (of those triggered by precondition violations) should be for them.
[...] but some messages will go through all these layers and be finally displayed to users.
They shouldn't.
These messages should provide as much information to them as we can provide.
No, the "detail" message is a hint to get at the code and correct the bug.
Users are the most important part of a system.
Most important for CM are the users who use CM _directly_. Apart from doing correct computations
(obviously), the library should be as easy as possible to use, while providing a robust and
clear design that can stand as an example of best programming practices and enhance development.
That may come at odds with short-term demands of some top-level (indirect) users. [Like those
who require to see error messages in French!]

The huge amount of error messages may be welcome in a high-level application, a sort of "mat(hematical)
lab(oratory)" powered by CM, but not in CM itself.

> Localization and Error Handling
> -------------------------------
>                 Key: MATH-361
>                 URL:
>             Project: Commons Math
>          Issue Type: Improvement
>    Affects Versions: 2.1
>            Reporter: Gilles
>            Priority: Minor
>         Attachments: l10n.tar.gz, res.tar.gz
> This proposal aims at easing the handling of error during algorithms development, and
also enhancing the flexibility of the error reporting (provide meaningful exception classes
and run-time selection of the localization formatting).
> More details at []

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message