Re: Error message style guide - Mailing list pgsql-hackers

Tom Lane writes:

> I think a style guide should just say "Keep primary messages short".

Right.

> 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."

I would prefer leaving the formatting to client and have the backend
provide a more semantic-type "markup".  For example the newline character
could be considered a paragraph break and within the paragraph the text
just flows.  (We could hack up some line-breaking logic in psql.)  Or a
really fancy solution:  Use the Unicode characters for line and paragraph
breaks.  *Really* fancy, admittedly.

> 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

I think format_type can remain an exception to that rule, one way or the
other.  If there are more of these, we need to think harder.

> 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"

I think the above is better.  I guess I don't quite follow you here.

> This works for primary messages, I think, but not detail and hint
> messages.  Can we use a different rule for detail/hint messages?

These rules weren't meant to apply to detail/hint.  We should probably
require those to be complete 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 put it in parentheses.  That normally indicates a subsidiary,
> less-important part of a sentence.

Yeah, the colon-style seems to be most wide-spread, also outside
PostgreSQL.

> Nonetheless I'm not sure that avoiding references to system calls will
> improve matters.  In particular, for cases that are really "can't
> happen" situations (eg, we are normally not expecting select(2) to
> fail), I'm not seeing the advantage of avoiding the reference.

It was mostly meant as a broad hint not to write "open() failed", which
can clearly be written more user-friendly without loss of information.
For less obvious cases we can use a mixed style. Say 'could not
synchronize file "%s" with disk (fsync failed)'.  That tells people at
least that it's got something to do with their I/O subsystem.

-- 
Peter Eisentraut   peter_e@gmx.net