Add description of error style.

src/tools/error_text

@@ -0,0 +1,299 @@
+To: Peter Eisentraut <peter_e@gmx.net>
+cc: pgsql-hackers@postgresql.org
+Subject: [HACKERS] Error message style guide, take 2
+Date: Wed, 14 May 2003 16:58:18 -0400
+From: Tom Lane <tgl@sss.pgh.pa.us>
+
+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