--- /dev/null
+From pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 12:14:19 2001
+Return-path: <pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org>
+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 <pgman@candle.pha.pa.us>; 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 <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
+ (envelope-from pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org)
+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 <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
+ (envelope-from peter_e@gmx.net)
+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 pgsql-hackers@postgresql.org; 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 pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:03 +0100
+Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
+From: Peter Eisentraut <peter_e@gmx.net>
+X-Sender: <peter@peter.localdomain>
+To: PostgreSQL Development <pgsql-hackers@postgresql.org>
+Subject: [HACKERS] Backend error message style issues
+Message-ID: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
+MIME-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Precedence: bulk
+Sender: pgsql-hackers-owner@postgresql.org
+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 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
+
+From pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 13:39:41 2001
+Return-path: <pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org>
+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 <pgman@candle.pha.pa.us>; 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 <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
+ (envelope-from pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org)
+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 <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
+ (envelope-from mascarm@mascari.com)
+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: <3C07DBAD.A9735975@mascari.com>
+Date: Fri, 30 Nov 2001 14:19:09 -0500
+From: Mike Mascari <mascarm@mascari.com>
+Organization: Mascari Development Inc.
+X-Mailer: Mozilla 4.77 [en] (WinNT; U)
+X-Accept-Language: en
+MIME-Version: 1.0
+To: Peter Eisentraut <peter_e@gmx.net>
+cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
+Subject: Re: [HACKERS] Backend error message style issues
+References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
+Content-Type: text/plain; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+Precedence: bulk
+Sender: pgsql-hackers-owner@postgresql.org
+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
+mascarm@mascari.com
+
+---------------------------(end of broadcast)---------------------------
+TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
+
+From pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 14:09:48 2001
+Return-path: <pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org>
+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 <pgman@candle.pha.pa.us>; 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 <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
+ (envelope-from pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org)
+Received: from sss.pgh.pa.us ([192.204.191.242])
+ by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
+ for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
+ (envelope-from tgl@sss.pgh.pa.us)
+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 <peter_e@gmx.net>
+cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
+Subject: Re: [HACKERS] Backend error message style issues
+In-Reply-To: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
+References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
+Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
+ message dated "Fri, 30 Nov 2001 19:12:16 +0100"
+Date: Fri, 30 Nov 2001 14:49:14 -0500
+Message-ID: <10303.1007149754@sss.pgh.pa.us>
+From: Tom Lane <tgl@sss.pgh.pa.us>
+Precedence: bulk
+Sender: pgsql-hackers-owner@postgresql.org
+Status: OR
+
+Peter Eisentraut <peter_e@gmx.net> 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 majordomo@postgresql.org
+
OSDN Git Service
