Neil, attached are three email messages dealing with error message
wording.
I like Tom's idea of coding only the messages that are common/user
errors and leaving the others with a catch-all code.
We now have more elog levels in 7.3, so it should be easier to classify
the messages.
I can see this job as several parts:
---------------------------------------------------------------------------
Cleanup of error wording, removal of function names. See attached
emails for possible standard.
---------------------------------------------------------------------------
Reporting of file, line, function reporting using GUC/SET variable. For
function names I see in the gcc 3.1 docs at
http://gcc.gnu.org/onlinedocs/gcc-3.1/cpp/Standard-Predefined-Macros.html:
C99 introduces __func__, and GCC has provided __FUNCTION__ for a long
time. Both of these are strings containing the name of the current
function (there are slight semantic differences; see the GCC manual).
Neither of them is a macro; the preprocessor does not know the name of
the current function. They tend to be useful in conjunction with
__FILE__ and __LINE__, though.
My gcc 2.95 (gcc version 2.95.2 19991024) supports both __FUNCTION__ and
__func__, even though they are not documented in the info manual pages I
have. I think we will need a configure.in test for this because it
isn't a macro you can #ifdef.
---------------------------------------------------------------------------
Actual error code numbers/letters. I think the new elog levels will
help with this. We have to decide if we want error numbers, or some
pneumonic like NOATTR or CONSTVIOL. I suggest the latter.
---------------------------------------------------------------------------
I think we have plenty of time to get this done for 7.3.
--
Bruce Momjian | http://candle.pha.pa.us
[EMAIL PROTECTED] | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
>From [EMAIL PROTECTED] Fri Nov 30
>12:14:19 2001
Return-path: <[EMAIL PROTECTED]>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUIEIR21802
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 13:14:18 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUI6ER13094
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
(envelope-from
[EMAIL PROTECTED])
Received: from moutvdom01.kundenserver.de (moutvdom01.kundenserver.de [195.20.224.200])
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUI58m98870
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
(envelope-from [EMAIL PROTECTED])
Received: from [195.20.224.208] (helo=mrvdom01.schlund.de)
by moutvdom01.kundenserver.de with esmtp (Exim 2.12 #2)
id 169s27-00049P-00
for [EMAIL PROTECTED]; Fri, 30 Nov 2001 19:05:07 +0100
Received: from p3e9e6fa2.dip0.t-ipconnect.de ([62.158.111.162])
by mrvdom01.schlund.de with esmtp (Exim 2.12 #2)
id 169s21-0001UP-00
for [EMAIL PROTECTED]; Fri, 30 Nov 2001 19:05:03 +0100
Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
From: Peter Eisentraut <[EMAIL PROTECTED]>
X-Sender: <[EMAIL PROTECTED]>
To: PostgreSQL Development <[EMAIL PROTECTED]>
Subject: [HACKERS] Backend error message style issues
Message-ID: <[EMAIL PROTECTED]>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk
Sender: [EMAIL PROTECTED]
Status: ORr
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 [EMAIL PROTECTED]
---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to [EMAIL PROTECTED] so that your
message can get through to the mailing list cleanly
>From [EMAIL PROTECTED] Fri Nov 30
>13:39:41 2001
Return-path: <[EMAIL PROTECTED]>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUJdfR29066
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 14:39:41 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUJXkR15701
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
(envelope-from
[EMAIL PROTECTED])
Received: from corvette.mascari.com (dhcp065-024-158-068.columbus.rr.com
[65.24.158.68])
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJMnm01940
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
(envelope-from [EMAIL PROTECTED])
Received: from mascari.com (ferrari.mascari.com [192.168.2.1])
by corvette.mascari.com (8.9.3/8.9.3) with ESMTP id OAA20637;
Fri, 30 Nov 2001 14:16:52 -0500
Message-ID: <[EMAIL PROTECTED]>
Date: Fri, 30 Nov 2001 14:19:09 -0500
From: Mike Mascari <[EMAIL PROTECTED]>
Organization: Mascari Development Inc.
X-Mailer: Mozilla 4.77 [en] (WinNT; U)
X-Accept-Language: en
MIME-Version: 1.0
To: Peter Eisentraut <[EMAIL PROTECTED]>
cc: PostgreSQL Development <[EMAIL PROTECTED]>
Subject: Re: [HACKERS] Backend error message style issues
References: <[EMAIL PROTECTED]>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: [EMAIL PROTECTED]
Status: OR
Peter Eisentraut wrote:
>
> 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.
For what its worth, Oracle 8 ships with an error.txt file which
dictates the message standards to which their products comply.
Roughly:
Size Of Message:
---------------
Cannot exceed 76 characters, even when embedded format specifiers
are apart of the message. Only
start-up and system-dependent messages can exceed 76 characters.
Simple Language:
---------------
Use non-cryptic messages and overly technical language.
Upper vs. Lowercase:
-------------------
Use uppercase for commands and keywords, lowercase for message
wording, including the first letter (which agrees with your use,
Peter).
Commands, Keywords, Parameter Values:
------------------------------------
When possible, give the command, keyword and parameters used in the
message.
BAD: The relation could not be created
GOOD: CREATE TABLE failed for table "foo" because the disk is full
Period:
------
Do not end messages with a period (also agrees with your
conclusion).
Numbers:
-------
Don't enclose numbers with special characters. For example:
BAD: rows returned by subquery (3) exceeded limit (1)
GOOD: the subquery returned 3 rows exceeding the 1 row limit
Quotes:
------
Don't use single or double quotes to emphasize a text variable or
command
Single Quotes:
-------------
Never use them.
Double Quotes:
-------------
Always and only use them to identify database objects.
BAD: Unable to drop table employees
GOOD: DROP TABLE of "employees" failed due to referential integrity
constraints
Ellipses:
--------
Don't use them.
BAD: Unable to drop column mascarm.employees.salary
GOOD: ALTER TABLE was unable to drop the column "salary" table
"employees" schema "mascarm"
Parentheses:
-----------
Always and only use parentheses for constraint names
BAD: not null constraint ri_employees violated
GOOD: not null constraint (ri_employees) violated
Brackets:
--------
Always and only used for program arguments
Grammar:
-------
Use complete sentences whenever possible without the trailing
period. Don't use multiple sentences. Use the active voice. Don't
use an aggressive tone.
Style:
-----
Make positive suggestions. Explain what is invalid and what is
valid.
Example:
BAD: file name invalid
BETTER: COPY failed because the file name was too long
Routine names:
-------------
Do not use routine names in messages. Again, agrees with you, Peter.
FWIW,
Mike Mascari
[EMAIL PROTECTED]
---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
>From [EMAIL PROTECTED] Fri Nov 30
>14:09:48 2001
Return-path: <[EMAIL PROTECTED]>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUK9lR02095
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 15:09:48 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUK3MR16820
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
(envelope-from
[EMAIL PROTECTED])
Received: from sss.pgh.pa.us ([192.204.191.242])
by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
for <[EMAIL PROTECTED]>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
(envelope-from [EMAIL PROTECTED])
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
by sss.pgh.pa.us (8.11.4/8.11.4) with ESMTP id fAUJnEi10307;
Fri, 30 Nov 2001 14:49:14 -0500 (EST)
To: Peter Eisentraut <[EMAIL PROTECTED]>
cc: PostgreSQL Development <[EMAIL PROTECTED]>
Subject: Re: [HACKERS] Backend error message style issues
In-Reply-To: <[EMAIL PROTECTED]>
References: <[EMAIL PROTECTED]>
Comments: In-reply-to Peter Eisentraut <[EMAIL PROTECTED]>
message dated "Fri, 30 Nov 2001 19:12:16 +0100"
Date: Fri, 30 Nov 2001 14:49:14 -0500
Message-ID: <[EMAIL PROTECTED]>
From: Tom Lane <[EMAIL PROTECTED]>
Precedence: bulk
Sender: [EMAIL PROTECTED]
Status: OR
Peter Eisentraut <[EMAIL PROTECTED]> writes:
> I hope we can work through all of these during the next development
> period.
Too bad we didn't do it *before* doing a lot of translation work :-(.
Yes, I agree that a pass of rationalizing the error messages would be
useful. Might want to think about that old bugaboo, error codes,
while we're at it. Also the perennial complaint that "ERROR" and
"DEBUG" macros tend to conflict with other things. As long as we're
going to touch many/all of the elog() calls, couldn't we try to clean
up all these issues?
> Which is better:
> function '%s' not found
> function "%s" not found
> function %s not found
Given that 'x' and "x" mean very different things in SQL, I think that
the first form is just plain wrong when an identifier is involved.
Unfortunately a lot of older code uses that style. I've tried to use
double quotes in new messages, but have restrained myself from wholesale
changes of existing messages.
> 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.
Sounds like a plan to me: put together a style guide first, and then
make a pass through the code to try to implement it.
regards, tom lane
---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
