Peter Eisentraut [EMAIL PROTECTED] writes:
Some people were mentioning an error message style guide. Here's a start
of one that I put together a while ago. Feel free to consider it.
Looks like a good start. But you expected quibbles, right? ;-)
The main part of a message should be at most 72 characters long. For
embedded format specifiers (%s, %d, etc.), a reasonable estimate of
the expected string should be taken into account. The rest should be
distributed to the detail and the hint parts.
This is not really workable to adhere to strictly. For example, a
message that includes more than one user identifier (eg, a table and
column name) fails the test immediately since each name might be
NAMEDATALEN-1 long. Even with only one identifier, I have nine
characters allowed for the error text ... less quotes and a space
makes six... less ERROR: leaves me with nothing. Okay, so you said
reasonable estimate not worst case, but unless you want to specify
what you think a reasonable estimate is, this guideline is useless.
I think a style guide should just say Keep primary messages short.
A message may not contain a newline or a tab.
This might work for primary messages given the keep it short dictum,
but it's quite unworkable for detail and hint messages --- we have some
of the latter that run to many lines.
How about something like Avoid tabs. Insert newlines as needed to keep
message lines shorter than X characters. Keep in mind that client
code might reformat long messages for its own purposes, so don't rely on
text layout for legibility.
Use quotes always to denote files, database objects, and other
variables of a character-string nature. Do not use them to mark up
nonvariable items.
One thing that's been annoying me recently is that some of our messages
exhibit double quoting, eg
regression=# select 'a' ### 'b';
ERROR: Unable to identify an operator '###' for types 'unknown' and 'unknown'
You will have to retype this query using an explicit cast
The reason this particular case happens is that the elog call puts
(single) quotes around the result of format_type_be --- and the latter
puts double quotes around names that seem to need it, which include
mixed-case names and (as in this case) names that are also SQL keywords.
Individually each of these choices seems defensible, but the result is
mighty ugly. How can we fix it?
NOTE: This format encourages embedding data items into the message in
grammatical positions instead of the old style 'invalid value: bar'.
I'm not sure that I like making messages be utterly dependent on the
presence of quotes to be decipherable. Would you consider the above
message to be better phrased as, say,
ERROR: Unable to identify an infix operator unknown ### unknown
Throw a few spaces and random characters into the type names, and this
gets very unreadable very fast. The invalid value: bar style has the
advantage that the message text is pretty clearly separated from the
object being complained about.
Do not end the message with a period. Do not even think about ending
a message with an exclamation point.
RATIONALE: Avoiding punctuation makes it easier for client
applications to embed the message into a variety of grammatical
contexts. Often, messages are not grammatically complete sentences
anyway. (And if they're long enough to be more than one sentence,
split them up.)
This works for primary messages, I think, but not detail and hint
messages. Can we use a different rule for detail/hint messages?
Use lower case for message wording, including the first letter of the
message. Use upper case for SQL commands and key words if the message
refers to the command string.
Again, this falls down for multi-sentence hints.
Instead of multiple sentences, consider using semicolons or commas.
Here's an example of an actual hint in the present sources. Do you
really want to convert it into one run-on sentence?
This error does *not* mean that you have run out of disk space.
It occurs when either the system limit for the maximum number of
semaphore sets (SEMMNI), or the system wide maximum number of
semaphores (SEMMNS), would be exceeded. You need to raise the
respective kernel parameter. Alternatively, reduce PostgreSQL's
consumption of semaphores by reducing its max_connections parameter
(currently %d).
The PostgreSQL Administrator's Guide contains more information about
configuring your system for PostgreSQL.
| 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. It also looks better and is
more flexible than colons or dashes to separate the sentences
We almost uniformly use could not open file %s: %m for this now. Is
the parenthesis style really better? I don't find it more natural. In
most cases, the %m part is the actually useful information, so it seems
odd to
