Re: Error message style guide

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(at)gmx(dot)net