Re: [HACKERS] Backend error message style issues - Mailing list 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@mascari.com

---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org