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 [EMAIL PROTECTED] so that your > message can get through to the mailing list cleanly > -- Bruce Momjian | http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073 ---------------------------(end of broadcast)--------------------------- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly