Thread: Error message style guide, take 2

Error message style guide, take 2

From
Tom Lane
Date:
I'm about to start going through the backend's elog() calls to update
them to ereport() style, add error code numbers, polish wording, etc.
So it's time to nail down our style guide for message wording.  Attached
is a revision of the draft that Peter posted on 14-March.  Any further
comments?

BTW, I'd like to SGML-ify this and put it into the developer's guide
somewhere; any thoughts where exactly?
        regards, tom lane



What goes where
---------------

The primary message should be short, factual, and avoid reference to
implementation details such as specific function names.  "Short" means
"should fit on one line under normal conditions".  Use a detail message if
needed to keep the primary message short, or if you feel a need to mention
implementation details such as the particular system call that failed.
Both primary and detail messages should be factual.  Use a hint message
for suggestions about what to do to fix the problem, especially if the
suggestion might not always be applicable.

For example, instead ofIpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m(plus a long addendum that is basically
ahint)
 
writePrimary:    Could not create shared memory segment: %mDetail:     Failed syscall was shmget(key=%d, size=%u,
0%o)Hint:      the addendum
 

RATIONALE: keeping the primary message short helps keep it to the point,
and lets clients lay out screen space on the assumption that one line is
enough for error messages.  Detail and hint messages may be relegated to a
verbose mode, or perhaps a pop-up error-details window.  Also, details and
hints would normally be suppressed from the server log to save space.
Reference to implementation details is best avoided since users don't know
the details anyway.


Formatting
----------

Don't put any specific assumptions about formatting into the message
texts.  Expect clients and the server log to wrap lines to fit their own
needs.  In long messages, newline characters (\n) may be used to indicate
suggested paragraph breaks.  Don't end a message with a newline.  Don't
use tabs or other formatting characters.  (In error context displays,
newlines are automatically added to separate levels of context such
as function calls.)

RATIONALE: Messages are not necessarily displayed on terminal-type
displays.  In GUI displays or browsers these formatting instructions
are at best ignored.


Quotation marks
---------------

English text should use double quotes when quoting is appropriate.
Text in other languages should consistently use one kind of quotes
that is consistent with publishing customs and computer output of
other programs.

RATIONALE: The choice of double quotes over single quotes is somewhat
arbitrary, but tends to be the preferred use.  Some have suggested
choosing the kind of quotes depending on the type of object according to
SQL conventions (namely, strings single quoted, identifiers double
quoted).  But this is a language-internal technical issue that many users
aren't even familiar with, it won't scale to other kinds of quoted terms,
it doesn't translate to other languages, and it's pretty pointless, too.


Use of quotes
-------------

Use quotes always to delimit file names, user-supplied identifiers,
and other variables that might contain words.  Do not use them to
mark up variables that will not contain words (for example, operator
names).

There are functions in the backend that will double-quote their own
output at need (for example, format_type_be()).  Do not put additional
quotes around the output of such functions.

RATIONALE: Objects can have names that create ambiguity when embedded
in a message.  Be consistent about denoting where a plugged-in name
starts and ends.  But don't clutter messages with unnecessary or
duplicate quote marks.


Grammar and punctuation
-----------------------

The rules are different for primary error messages and for detail/hint
messages:

Primary error messages: Do not capitalize the first letter.  Do not end a
message with a period.  Do not even think about ending a message with an
exclamation point.

Detail and hint messages: Use complete sentences, and end each with
a period.  Capitalize the starts of sentences.

RATIONALE: Avoiding punctuation makes it easier for client applications to
embed the message into a variety of grammatical contexts.  Often, primary
messages are not grammatically complete sentences anyway.  (And if they're
long enough to be more than one sentence, they should be split into
primary and detail parts.)  However, detail and hint messages are longer
and may need to include multiple sentences.  For consistency, they should
follow complete-sentence style even when there's only one sentence.


Upper case vs. lower case
-------------------------

Use lower case for message wording, including the first letter of a
primary error message.  Use upper case for SQL commands and key words if
they appear in the message.

RATIONALE: It's easier to make everything look more consistent this
way, since some messages are complete sentences and some not.


Avoid passive voice
-------------------

Use the active voice.  Use complete sentences when there is an acting
subject ("A could not do B").  Use telegram style without subject if
the subject would be the program itself; do not use "I" for the
program.

RATIONALE: The program is not human.  Don't pretend otherwise.


Present vs past tense
---------------------

Use past tense if an attempt to do something failed, but could perhaps
succeed next time (perhaps after fixing some problem).  Use present tense
if the failure is certainly permanent.

There is a nontrivial semantic difference between sentences of the
form
could not open file "%s": %m

and
cannot open file "%s"

The first one means that the attempt to open the file failed.  The
message should give a reason, such as "disk full" or "file doesn't
exist".  The past tense is appropriate because next time the disk
might not be full anymore or the file in question may exist.

The second form indicates the the functionality of opening the named
file does not exist at all in the program, or that it's conceptually
impossible.  The present tense is appropriate because the condition
will persist indefinitely.

RATIONALE: Granted, the average user will not be able to draw great
conclusions merely from the tense of the message, but since the
language provides us with a grammar we should use it correctly.


Type of the object
------------------

When citing the name of an object, state what kind of object it is.

RATIONALE: Else no one will know what "foo.bar.baz" is.


Brackets
--------

Square brackets are only to be used (1) in command synopses to denote
optional arguments, or (2) to denote an array subscript.

RATIONALE: Anything else does not correspond to widely-known customary
usage and will confuse people.


Assembling error messages
-------------------------

When a message includes text that is generated elsewhere, embed it in
this style:
could not open file %s: %m

RATIONALE: It would be difficult to account for all possible error codes
to paste this into a single smooth sentence, so some sort of punctuation
is needed.  Putting the embedded text in parentheses has also been
suggested, but it's unnatural if the embedded text is likely to be the
most important part of the message, as is often the case.


Reasons for errors
------------------

Messages should always state the reason why an error occurred.
For example:

BAD:    could not open file %s
BETTER:    could not open file %s (I/O failure)

If no reason is known you better fix the code. ;-)


Function names
--------------

Don't include the name of the reporting routine in the error text.
We have other mechanisms for finding that out when needed, and for
most users it's not helpful information.  If the error text doesn't
make as much sense without the function name, reword it.

BAD:    pg_atoi: error in "z": can't parse "z"
BETTER:    invalid input syntax for integer: "z"

Avoid mentioning called function names, either; instead say what the code
was trying to do:

BAD:    open() failed: %m
BETTER:    could not open file %s: %m

If it really seems necessary, mention the system call in the detail
message.  (In some cases, providing the actual values passed to the
system call might be appropriate information for the detail message.)

RATIONALE: Users don't know what all those functions do.


Tricky words to avoid
---------------------

unable:

"unable" is nearly the passive voice.  Better use "cannot" or "could
not", as appropriate.

bad:

Error messages like "bad result" are really hard to interpret
intelligently.  It's better to write why the result is "bad", e.g.,
"invalid format".

illegal:

"Illegal" stands for a violation of the law, the rest is "invalid".
Better yet, say why it's invalid.

unknown:

Try to avoid "unknown".  Consider "error: unknown response".  If you
don't know what the response is, how do you know it's erroneous?
"Unrecognized" is often a better choice.  Also, be sure to include the
value being complained of.

BAD:    unknown node type
BETTER:    unrecognized node type: 42

find vs. exists:

If the program uses a nontrivial algorithm to locate a resource (e.g., a
path search) and that algorithm fails, it is fair to say that the program
couldn't "find" the resource.  If, on the other hand, the expected
location of the resource is known but the program cannot access it there
then say that the resource doesn't "exist".  Using "find" in this case
sounds weak and confuses the issue.


Proper spelling
---------------

Spell out words in full.  For instance, avoid:

spec
stats
parens
auth
xact

RATIONALE: This will improve consistency.


Re: Error message style guide, take 2

From
"Dann Corbit"
Date:
I really like the way the RDB and VMS log error messages.
They are categorized with:
%<APP>-E-
%<APP>-W-
%<APP>-I-
For Error, Warning, and Informational level messages.

For example:
%DCL-I-SUPERSEDE, previous value of CNXSERVICE has been superseded
(DCL reports that an environmental variable has replaced an older value)

%RDB-W-META_WARN, metadata successfully updated with the reported
warning -RDMS-W-PRFCREATED, some users or roles were created
(A 'grant all' on table <table> to <user> causes RDB to warn that
users/roles were created)

%RDB-E-STREAM_EOF, attempt to fetch past end of record stream
(Cursor fetch on end of stream [one error that really isn't much of an
error])

It is especially nice when you are searching through a detailed log
file.  You can look for all warnings/errors by searching for a percent
sign.  You can search for error level messages by searching for a "-E-"
and that sort of thing.


Re: Error message style guide, take 2

From
Peter Eisentraut
Date:
Tom Lane writes:

> So it's time to nail down our style guide for message wording.  Attached
> is a revision of the draft that Peter posted on 14-March.  Any further
> comments?

Looks good.  I'm sure we'll find some more issues as we go along.

This is slightly unrelated, but what kind of switches should client
libraries have to control the level of detail that the application sees?
Most interfaces that are standardized outside of PostgreSQL have only one
error message function, so I'm afraid what will happen is that they paste
it all together by default and the distinction between primary and detail
will become moot.  And I think I do want the detail in the server log,
too.

> BTW, I'd like to SGML-ify this and put it into the developer's guide
> somewhere; any thoughts where exactly?

I suggest the chapter with the source code formatting issues, as part of a
general "coding style".

-- 
Peter Eisentraut   peter_e@gmx.net



Re: Error message style guide, take 2

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> This is slightly unrelated, but what kind of switches should client
> libraries have to control the level of detail that the application sees?

Not sure ... feel free to make a proposal.  I had been planning to add
function(s) to libpq to allow individual error fields to be extracted,
but you are right that there'll need to be some way to customize the
behavior of PQerrorMessage() as well.

> And I think I do want the detail in the server log, too.

I had been thinking that it might be useful to have something
corresponding to min_log_level, ie "show details if error level >= X".
(I'm thinking that the one switch would control logging of all details,
ie, everything but the primary error message.)

I'm not completely happy with that though, because of two thoughts:

(1) We probably want details always for anything that prevents
postmaster startup --- for instance, all that hard-won verbiage about
shmem configuration problems will never be seen again if the default
is not to put it into the postmaster log.

(2) On the other hand, there are a lot of perfectly ordinary and
uninteresting "FATAL" conditions during backend start --- misspelled
database name, for example.  The default should not include logging
details for these.

Perhaps we could put in some hack to vary the logging level depending
on whether we are in postmaster start, postmaster run, backend start,
backend run state.  Not sure though.  Any ideas?
        regards, tom lane


Re: Error message style guide, take 2

From
Joe Conway
Date:
Tom Lane wrote:
> Not sure ... feel free to make a proposal.  I had been planning to add
> function(s) to libpq to allow individual error fields to be extracted,
> but you are right that there'll need to be some way to customize the
> behavior of PQerrorMessage() as well.

What about a new connection string keyword that controls how much detail 
is included in PQerrorMessage() for the current session? Maybe 
message_verbosity as a level something like:

0 - no message text (not sure if this makes sense)
1 - short message only
2 - short plus detailed
3 - short plus detailed plus hint
4 - ?
5 - all details (short, detailed, hint, file, line, function name, etc)

Or perhaps better would be a new GUC variable?

> Perhaps we could put in some hack to vary the logging level depending
> on whether we are in postmaster start, postmaster run, backend start,
> backend run state.  Not sure though.  Any ideas?

Seems reasonable to have distinct postmaster_log_min_messages from 
backend_log_min_messages. And in similar fashion, 
postmaster_message_verbosity and backend_message_verbosity. Then use the 
verbosity setting to determine what text is actually logged.

Joe




Re: Error message style guide, take 2

From
Kevin Brown
Date:
Dann Corbit wrote:
> I really like the way the RDB and VMS log error messages.
> They are categorized with:
> %<APP>-E-
> %<APP>-W-
> %<APP>-I-
> For Error, Warning, and Informational level messages.
> 
> For example:
> %DCL-I-SUPERSEDE, previous value of CNXSERVICE has been superseded
> (DCL reports that an environmental variable has replaced an older value)
> 
> %RDB-W-META_WARN, metadata successfully updated with the reported
> warning -RDMS-W-PRFCREATED, some users or roles were created
> (A 'grant all' on table <table> to <user> causes RDB to warn that
> users/roles were created)
> 
> %RDB-E-STREAM_EOF, attempt to fetch past end of record stream
> (Cursor fetch on end of stream [one error that really isn't much of an
> error])
> 
> It is especially nice when you are searching through a detailed log
> file.  You can look for all warnings/errors by searching for a percent
> sign.  You can search for error level messages by searching for a "-E-"
> and that sort of thing.

I'm very much in agreement here.  In addition to the advantages listed
above, this scheme is vastly superior to simply issuing error numbers
because the reader can at least get an idea of what the error itself
actually is even if he doesn't have the detail text associated with
the error.

I might be inclined (to make it slightly easier on the newbies) to
have them be of the form %<APP>-INFO-, %<APP>-WARN-, and
%<APP>-ERROR-, but that's the only improvement to the scheme I can
think of.

If it's not too late, I think we should seriously consider using that
error code scheme throughout PostgreSQL.



-- 
Kevin Brown                          kevin@sysexperts.com


Re: Error message style guide, take 2

From
Tom Lane
Date:
Kevin Brown <kevin@sysexperts.com> writes:
> Dann Corbit wrote:
>> I really like the way the RDB and VMS log error messages.

> I'm very much in agreement here.  In addition to the advantages listed
> above, this scheme is vastly superior to simply issuing error numbers
> because the reader can at least get an idea of what the error itself
> actually is even if he doesn't have the detail text associated with
> the error.

I didn't actually see anything to it except for a very ugly spelling of
ERROR:, NOTICE:, WARNING:, etc.  What exactly is there in their scheme
that you can't do as well or better with our existing practices?
        regards, tom lane


Re: Error message style guide, take 2

From
"Dann Corbit"
Date:
> -----Original Message-----
> From: Tom Lane [mailto:tgl@sss.pgh.pa.us]
> Sent: Friday, May 16, 2003 2:45 PM
> To: Kevin Brown
> Cc: pgsql-hackers@postgresql.org
> Subject: Re: [HACKERS] Error message style guide, take 2
>
>
> Kevin Brown <kevin@sysexperts.com> writes:
> > Dann Corbit wrote:
> >> I really like the way the RDB and VMS log error messages.
>
> > I'm very much in agreement here.  In addition to the
> advantages listed
> > above, this scheme is vastly superior to simply issuing
> error numbers
> > because the reader can at least get an idea of what the
> error itself
> > actually is even if he doesn't have the detail text associated with
> > the error.
>
> I didn't actually see anything to it except for a very ugly
> spelling of ERROR:, NOTICE:, WARNING:, etc.  What exactly is
> there in their scheme that you can't do as well or better
> with our existing practices?

There is a unique signature that makes things easy to find. A grep for
'%' will find all errors, warnings and informational messages.  A grep
for '-E-' will find all errors.  The words 'error', 'warning' and
'notice' are not likely to be unique.  A single '%' sign might turn up
in the text of a message (e.g. a badly formed like clause) but it not
terribly common in use.  That might be done a bit better.  Maybe
something like '!%>' or some other very unlikely combination would be
better.  But not too long.  Then it would be hard to remember.


Re: Error message style guide, take 2

From
Tom Lane
Date:
"Dann Corbit" <DCorbit@connx.com> writes:
>> I didn't actually see anything to it except for a very ugly 
>> spelling of ERROR:, NOTICE:, WARNING:, etc.  What exactly is 
>> there in their scheme that you can't do as well or better 
>> with our existing practices?

> There is a unique signature that makes things easy to find. A grep for
> '%' will find all errors, warnings and informational messages.  A grep
> for '-E-' will find all errors.  The words 'error', 'warning' and
> 'notice' are not likely to be unique.

You think grep "ERROR:" is likely to get more false hits than grep "-E-"?
Somehow I doubt it.
        regards, tom lane


Re: Error message style guide, take 2

From
Kevin Brown
Date:
Tom Lane wrote:
> Kevin Brown <kevin@sysexperts.com> writes:
> > Dann Corbit wrote:
> >> I really like the way the RDB and VMS log error messages.
> 
> > I'm very much in agreement here.  In addition to the advantages listed
> > above, this scheme is vastly superior to simply issuing error numbers
> > because the reader can at least get an idea of what the error itself
> > actually is even if he doesn't have the detail text associated with
> > the error.
> 
> I didn't actually see anything to it except for a very ugly spelling of
> ERROR:, NOTICE:, WARNING:, etc.  What exactly is there in their scheme
> that you can't do as well or better with our existing practices?

If the text of the error message is always reported to the client
library *and* the client always reports the full text of the error to
the user (and perhaps to the log), then clearly there would be no
advantage of the RDB/VMS error scheme over simply reporting error
numbers + associated error text.

But far too often, I've seen client code (not necessarily PG-related,
mind you) report an error number only without bothering to also
include the error text.  Since I was under the impression that we were
going to separate error codes from error text in the protocol, it's
possible for a client to report an error code without also reporting
the corresponding error text.  In that situation, the RDB/VMS error
scheme has significant advantages.

So it all depends on what happens on the client end, but I'd much
rather give users as much to work with as possible, even in the face
of poorly written clients.

If you think of how often you've seen programs report an error number
generated by a system call without bothering to also report the
associated error text (via strerror(), for instance), then you know
exactly what I'm talking about.

The RDB/VMS scheme gives you a great deal of readily-accessible
information in a very small package.  Error numbers don't.  So given
the choice, I'd rather go with the RDB/VMS scheme if there are no
significant drawbacks involved.

We certainly don't have to adopt that specific scheme, but I think it
would be wise to adopt an error code scheme that has the same
advantages.  For that purpose, the RDB/VMS scheme is probably at least
as good as any other.


-- 
Kevin Brown                          kevin@sysexperts.com


Re: Error message style guide, take 2

From
Bruce Momjian
Date:
I have added this email to CVS as src/tools/error_text.  Any changes to
it?

---------------------------------------------------------------------------

Tom Lane wrote:
> I'm about to start going through the backend's elog() calls to update
> them to ereport() style, add error code numbers, polish wording, etc.
> So it's time to nail down our style guide for message wording.  Attached
> is a revision of the draft that Peter posted on 14-March.  Any further
> comments?
> 
> BTW, I'd like to SGML-ify this and put it into the developer's guide
> somewhere; any thoughts where exactly?
> 
>             regards, tom lane
> 
> 
> 
> What goes where
> ---------------
> 
> The primary message should be short, factual, and avoid reference to
> implementation details such as specific function names.  "Short" means
> "should fit on one line under normal conditions".  Use a detail message if
> needed to keep the primary message short, or if you feel a need to mention
> implementation details such as the particular system call that failed.
> Both primary and detail messages should be factual.  Use a hint message
> for suggestions about what to do to fix the problem, especially if the
> suggestion might not always be applicable.
> 
> For example, instead of
>     IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
>     (plus a long addendum that is basically a hint)
> write
>     Primary:    Could not create shared memory segment: %m
>     Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o)
>     Hint:       the addendum
> 
> RATIONALE: keeping the primary message short helps keep it to the point,
> and lets clients lay out screen space on the assumption that one line is
> enough for error messages.  Detail and hint messages may be relegated to a
> verbose mode, or perhaps a pop-up error-details window.  Also, details and
> hints would normally be suppressed from the server log to save space.
> Reference to implementation details is best avoided since users don't know
> the details anyway.
> 
> 
> Formatting
> ----------
> 
> Don't put any specific assumptions about formatting into the message
> texts.  Expect clients and the server log to wrap lines to fit their own
> needs.  In long messages, newline characters (\n) may be used to indicate
> suggested paragraph breaks.  Don't end a message with a newline.  Don't
> use tabs or other formatting characters.  (In error context displays,
> newlines are automatically added to separate levels of context such
> as function calls.)
> 
> RATIONALE: Messages are not necessarily displayed on terminal-type
> displays.  In GUI displays or browsers these formatting instructions
> are at best ignored.
> 
> 
> Quotation marks
> ---------------
> 
> English text should use double quotes when quoting is appropriate.
> Text in other languages should consistently use one kind of quotes
> that is consistent with publishing customs and computer output of
> other programs.
> 
> RATIONALE: The choice of double quotes over single quotes is somewhat
> arbitrary, but tends to be the preferred use.  Some have suggested
> choosing the kind of quotes depending on the type of object according to
> SQL conventions (namely, strings single quoted, identifiers double
> quoted).  But this is a language-internal technical issue that many users
> aren't even familiar with, it won't scale to other kinds of quoted terms,
> it doesn't translate to other languages, and it's pretty pointless, too.
> 
> 
> Use of quotes
> -------------
> 
> Use quotes always to delimit file names, user-supplied identifiers,
> and other variables that might contain words.  Do not use them to
> mark up variables that will not contain words (for example, operator
> names).
> 
> There are functions in the backend that will double-quote their own
> output at need (for example, format_type_be()).  Do not put additional
> quotes around the output of such functions.
> 
> RATIONALE: Objects can have names that create ambiguity when embedded
> in a message.  Be consistent about denoting where a plugged-in name
> starts and ends.  But don't clutter messages with unnecessary or
> duplicate quote marks.
> 
> 
> Grammar and punctuation
> -----------------------
> 
> The rules are different for primary error messages and for detail/hint
> messages:
> 
> Primary error messages: Do not capitalize the first letter.  Do not end a
> message with a period.  Do not even think about ending a message with an
> exclamation point.
> 
> Detail and hint messages: Use complete sentences, and end each with
> a period.  Capitalize the starts of sentences.
> 
> RATIONALE: Avoiding punctuation makes it easier for client applications to
> embed the message into a variety of grammatical contexts.  Often, primary
> messages are not grammatically complete sentences anyway.  (And if they're
> long enough to be more than one sentence, they should be split into
> primary and detail parts.)  However, detail and hint messages are longer
> and may need to include multiple sentences.  For consistency, they should
> follow complete-sentence style even when there's only one sentence.
> 
> 
> Upper case vs. lower case
> -------------------------
> 
> Use lower case for message wording, including the first letter of a
> primary error message.  Use upper case for SQL commands and key words if
> they appear in the message.
> 
> RATIONALE: It's easier to make everything look more consistent this
> way, since some messages are complete sentences and some not.
> 
> 
> Avoid passive voice
> -------------------
> 
> Use the active voice.  Use complete sentences when there is an acting
> subject ("A could not do B").  Use telegram style without subject if
> the subject would be the program itself; do not use "I" for the
> program.
> 
> RATIONALE: The program is not human.  Don't pretend otherwise.
> 
> 
> Present vs past tense
> ---------------------
> 
> Use past tense if an attempt to do something failed, but could perhaps
> succeed next time (perhaps after fixing some problem).  Use present tense
> if the failure is certainly permanent.
> 
> There is a nontrivial semantic difference between sentences of the
> form
> 
>     could not open file "%s": %m
> 
> and
> 
>     cannot open file "%s"
> 
> The first one means that the attempt to open the file failed.  The
> message should give a reason, such as "disk full" or "file doesn't
> exist".  The past tense is appropriate because next time the disk
> might not be full anymore or the file in question may exist.
> 
> The second form indicates the the functionality of opening the named
> file does not exist at all in the program, or that it's conceptually
> impossible.  The present tense is appropriate because the condition
> will persist indefinitely.
> 
> RATIONALE: Granted, the average user will not be able to draw great
> conclusions merely from the tense of the message, but since the
> language provides us with a grammar we should use it correctly.
> 
> 
> Type of the object
> ------------------
> 
> When citing the name of an object, state what kind of object it is.
> 
> RATIONALE: Else no one will know what "foo.bar.baz" is.
> 
> 
> Brackets
> --------
> 
> Square brackets are only to be used (1) in command synopses to denote
> optional arguments, or (2) to denote an array subscript.
> 
> RATIONALE: Anything else does not correspond to widely-known customary
> usage and will confuse people.
> 
> 
> Assembling error messages
> -------------------------
> 
> When a message includes text that is generated elsewhere, embed it in
> this style:
> 
>     could not open file %s: %m
> 
> RATIONALE: It would be difficult to account for all possible error codes
> to paste this into a single smooth sentence, so some sort of punctuation
> is needed.  Putting the embedded text in parentheses has also been
> suggested, but it's unnatural if the embedded text is likely to be the
> most important part of the message, as is often the case.
> 
> 
> Reasons for errors
> ------------------
>
> Messages should always state the reason why an error occurred.
> For example:
> 
> BAD:    could not open file %s
> BETTER:    could not open file %s (I/O failure)
> 
> If no reason is known you better fix the code. ;-)
> 
> 
> Function names
> --------------
> 
> Don't include the name of the reporting routine in the error text.
> We have other mechanisms for finding that out when needed, and for
> most users it's not helpful information.  If the error text doesn't
> make as much sense without the function name, reword it.
> 
> BAD:    pg_atoi: error in "z": can't parse "z"
> BETTER:    invalid input syntax for integer: "z"
> 
> Avoid mentioning called function names, either; instead say what the code
> was trying to do:
> 
> BAD:    open() failed: %m
> BETTER:    could not open file %s: %m
> 
> If it really seems necessary, mention the system call in the detail
> message.  (In some cases, providing the actual values passed to the
> system call might be appropriate information for the detail message.)
> 
> RATIONALE: Users don't know what all those functions do.
> 
> 
> Tricky words to avoid
> ---------------------
> 
> unable:
> 
> "unable" is nearly the passive voice.  Better use "cannot" or "could
> not", as appropriate.
> 
> bad:
> 
> Error messages like "bad result" are really hard to interpret
> intelligently.  It's better to write why the result is "bad", e.g.,
> "invalid format".
> 
> illegal:
> 
> "Illegal" stands for a violation of the law, the rest is "invalid".
> Better yet, say why it's invalid.
> 
> unknown:
> 
> Try to avoid "unknown".  Consider "error: unknown response".  If you
> don't know what the response is, how do you know it's erroneous?
> "Unrecognized" is often a better choice.  Also, be sure to include the
> value being complained of.
> 
> BAD:    unknown node type
> BETTER:    unrecognized node type: 42
> 
> find vs. exists:
> 
> If the program uses a nontrivial algorithm to locate a resource (e.g., a
> path search) and that algorithm fails, it is fair to say that the program
> couldn't "find" the resource.  If, on the other hand, the expected
> location of the resource is known but the program cannot access it there
> then say that the resource doesn't "exist".  Using "find" in this case
> sounds weak and confuses the issue.
> 
> 
> Proper spelling
> ---------------
> 
> Spell out words in full.  For instance, avoid:
> 
> spec
> stats
> parens
> auth
> xact
> 
> RATIONALE: This will improve consistency.
> 
> ---------------------------(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
> 

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: Error message style guide, take 2

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> I have added this email to CVS as src/tools/error_text.  Any changes to
> it?

Waste of CVS space; the real documentation is in SGML:
http://developer.postgresql.org/docs/postgres/error-style-guide.html
        regards, tom lane


Re: Error message style guide, take 2

From
Bruce Momjian
Date:
Oh, removed.

---------------------------------------------------------------------------

Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > I have added this email to CVS as src/tools/error_text.  Any changes to
> > it?
> 
> Waste of CVS space; the real documentation is in SGML:
> http://developer.postgresql.org/docs/postgres/error-style-guide.html
> 
>             regards, tom lane
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 8: explain analyze is your friend
> 

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073