db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Van Couvering <David.Vancouver...@Sun.COM>
Subject Re: DERBY-1376 - Text for exceptions - File java/engine/org/apache/derby/loc/messages_en.properties
Date Tue, 06 Jun 2006 17:08:59 GMT
IMHO, clear error messages are KEY to acceptance in production 
environments.  I did an interview of about 30 DBAs a few years ago, and 
they consistently listed clear error messages as higher priority than 
almost anything else.  The reason?  They are constantly being pounded 
with 99.99% uptime, and a down database is a REAL problem.  A bad error 
message can significantly impact the time that the database is down. 
This combined with excellent trace facilities and diagnostics is what 
customers seem to regularly ask for.

The problem often is that the engineer writing the code and thus 
creating the error messages is down in the trenches and often can't see 
the forest for the trees.  Their messages are for themselves, not 
necessarily for the customers.

I would love to see an approach where error messages are regularly 
reviewed by the tech pubs folks, and preferably our users, and go 
through a process of getting revised.

I also think it would be good to have guidelines for writing error 
messages.  I think they can be as simple as: "an error message should 
talk to the user, not to the developer.  The error should be explained 
from the perspective of the user, a probable cause should be provided, 
as well as a suggested course of action."

At one project in Sun you actually had an API that *required* you to 
provide the error messages, the probable cause, and a recommended course 
of action as three separate messages.  Just to drive the point home.

I'd be happy to (a) start a Wiki with guidelines for writing error 
messages and (b) participate in any kind of review we make of the error 
messages.  If you want to drive this error message review, Halley, that 
would be *great*.

Thanks,

David

Halley Pacheco de Oliveira wrote:
> Hi,
> 
> I'm translating the file java/engine/org/apache/derby/loc/messages_en.properties and
sometimes,
> when I can't understand the meaning of a message, I search for the message in the source
code to
> discover it's meaning.
> 
> The issue DERBY-1376 was open because I couldn't see any problem with the fact that "Log
directory
> exists". The existence of a directory is not a problem by itself. When reading the source
code in
> LogToFile.java file I saw the comment "// make sure log directory is empty", and the
message being
> showed only if the log directory is not empty, not if it exists.
> 
> I know it is a minor problem, almost insignificant, but I'm also having problems with
others
> messages when translating them.
> 
> For example, message "XIE06.S=Entity name was null." wasn't clear for me too, and when
I looked at
> the source code I saw the comment "Raised if, the entity (ie table/view) for import/export
is
> missing in the database.". So, again, the comment in the source code is easier to understand
than
> the message being showed to the user. There are others like this one as, for example,
for the
> message "XIE05.S=Data file cannot be null." the comment in the source code is "Raised
if, null is
> passed for data file url."
> 
> For me the biggest problem to overcome has being the translation of the message "XBM08.D=Could
not
> instantiage {0} StorageFactory class {1}." I just can't understand the meaning of this
telegraphic
>  message even reading the source code, shown below, and would appreciate if someone could
explain
> it to me.
> 
> private PersistentService getPersistentService( final String className, String subSubProtocol)
> throws StandardException
> {
> if( className == null)
> return null;
> Class storageFactoryClass = null;
> try
> {
> storageFactoryClass = Class.forName( className);
> }
> catch (Throwable e)
> {
> throw StandardException.newException( SQLState.INSTANTIATE_STORAGE_FACTORY_ERROR,
> e,
> subSubProtocol, className);
> }
> return new StorageFactoryService( subSubProtocol, storageFactoryClass);
> } // end of getPersistentService
> 
> The reason for me to write this email is to ask if someone at ASF revised these messages,
and if
> someone agrees that it would be good to revise these messages, since they are all that
end users
> have.
> 
> Thanks,
> Halley
> 
> 
> 
> __________________________________________________
> Fale com seus amigos  de gra├ža com o novo Yahoo! Messenger 
> http://br.messenger.yahoo.com/ 

Mime
View raw message