From: | Mike Mascari <mascarm(at)mascari(dot)com> |
---|---|
To: | Peter Eisentraut <peter_e(at)gmx(dot)net> |
Cc: | PostgreSQL Development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Backend error message style issues |
Date: | 2001-11-30 19:19:09 |
Message-ID: | 3C07DBAD.A9735975@mascari.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
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
mascarm(at)mascari(dot)com
From | Date | Subject | |
---|---|---|---|
Next Message | Tom Lane | 2001-11-30 19:40:44 | Re: initdb + locale problem |
Previous Message | Barry Lind | 2001-11-30 19:03:44 | Re: [HACKERS] JDBC improvements |