[HACKERS] Backend error message style issues - Mailing list pgsql-hackers

Now that we've gone through nearly one development cycle with national
language support, I'd like to bring up a number of issues concerning the
style of the backend error messages that make life difficult, but probably
not only for the translators but for users as well.  Not all of these are
strictly translation issues, but the message catalogs make for a good
overview of what's going on.

I hope we can work through all of these during the next development
period.

Prefixing messages with command names
-------------------------------------

For instance,

| CREATE DATABASE: permission denied

This "command: message" style is typical for command-line programs and
it's pretty useful there if you run many commands in a pipe.  The same
usefulness could probably be derived if you run many SQL commands in a
function.  (Just "permission denied" would be very confusing there!)

If we want to use that style we should make it consistent and we should
automate it.  Via the "command tag" mechanism we already know what command
we're executing, so we can automatically prefix all messages that way.  It
could even be switched off by the user if it's deemed annoying.


Prefixing messages with function names
--------------------------------------

The function names obviously have no meaning to the user.  It is claimed
that they allow a developer to locate the place the error was raised
faster, but that's only half the truth.  Firstly, this whole thing doesn't
work if the displayed name of the function was actually passed in from
elsewhere.  Then it takes you three times longer to locate the source
because you *think* you know where it was but it's not there.  Secondly,
a developer doesn't have the need to locate every error.  For instance,

| ExecAppend: rejected due to CHECK constraint foo

There's no need to debug anything there, it's a perfectly normal use
situation.

I think the key here is to distinguish error messages that are perfectly
normal user-level events from messages which really represent an "assert
failure, but continue gracefully", such as

| initGISTstate: numberOfAttributes %d > %d

The latter could better be written something like

| BETTER_BE_TRUE(index->rd_att->natts > INDEX_MAX_KEYS);

we could lead to an error message in the style of an assert failure,
including the expression in question and file and line information (and
bug reporting suggestions).  This way the developer doesn't have to write
any message text at all but still gets much better information to locate
the source.  (E.g., note that the tested variable isn't even called
"numberOfAttributes".)

The exact API could be tuned to include some other information such as an
informal message, but I think something along these lines needs to be
worked out.


Quoting
-------

Which is better:

function '%s' not found
function "%s" not found
function %s not found

I think two kinds of quotes is looking messy.  Personal suggestion:
double quotes.


Capitalization and punctuation
------------------------------

Which one?

ERROR:  Permission denied.
ERROR:  Permission denied
ERROR:  permission denied

I have personally used the GNU-recommended way which is the third, mostly
just because it is *some* standardized way.  I don't have a strong feeling
about the initial capitalization, but I'm against the periods except when
the message is really a sentence and it contains some other punctuation
(commas, etc.) or the message consists of more than one sentence.


Grammatical structure and choice of words
-----------------------------------------

There are many others besides the above choices:

ERROR: Permission was denied.
ERROR: You don't have permission to do <task>.
ERROR: Permission to do <task> was denied.
ERROR: <task>: Permission denied

In other cases there's a sea of possibilities:

couldn't find THING
can't find THING
THING wasn't found
unable to locate THING
lookup of THING failed
THING doesn't exist

Strictly speaking, there are at least four different meanings among those
six messages, yet they're used mostly randomly.

There are a number of things to think about here: active vs passive, can
vs could, complete sentence vs telegram style, use of colons, addressing
the user with "you [cannot...]".

And please let's not have the program talk in the "I"-form ("I have rolled
back the current transaction ...").



More esoteric discussions are also possible, but I'm going to postpone
those. ;-)  However, I think it's worth working on this and perhaps
putting together a "manual of style" that applies to all parts of
PostgreSQL.  This would significantly improve the overall perceived
quality.  Some projects like KDE, GNU, and GCC have teams that discuss
these kinds of things and it's definitely showing.

-- 
Peter Eisentraut   peter_e@gmx.net


---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly