diff options
Diffstat (limited to 'doc/src/sgml/html/error-style-guide.html')
| -rw-r--r-- | doc/src/sgml/html/error-style-guide.html | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/doc/src/sgml/html/error-style-guide.html b/doc/src/sgml/html/error-style-guide.html new file mode 100644 index 0000000..2d6861b --- /dev/null +++ b/doc/src/sgml/html/error-style-guide.html @@ -0,0 +1,250 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.3. Error Message Style Guide</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server" /><link rel="next" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.3. Error Message Style Guide</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Next</a></td></tr></table><hr /></div><div class="sect1" id="ERROR-STYLE-GUIDE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.3. Error Message Style Guide</h2></div></div></div><p> + This style guide is offered in the hope of maintaining a consistent, + user-friendly style throughout all the messages generated by + <span class="productname">PostgreSQL</span>. + </p><div class="simplesect" id="id-1.10.7.4.3"><div class="titlepage"><div><div><h3 class="title">What Goes Where</h3></div></div></div><p> + The primary message should be short, factual, and avoid reference to + implementation details such as specific function names. + <span class="quote">“<span class="quote">Short</span>”</span> means <span class="quote">“<span class="quote">should fit on one line under normal + conditions</span>”</span>. 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. + </p><p> + For example, instead of: +</p><pre class="programlisting"> +IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m +(plus a long addendum that is basically a hint) +</pre><p> + write: +</p><pre class="programlisting"> +Primary: could not create shared memory segment: %m +Detail: Failed syscall was shmget(key=%d, size=%u, 0%o). +Hint: the addendum +</pre><p> + </p><p> + 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 can 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 + aren't expected to know the details. + </p></div><div class="simplesect" id="id-1.10.7.4.4"><div class="titlepage"><div><div><h3 class="title">Formatting</h3></div></div></div><p> + 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) can 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.) + </p><p> + Rationale: Messages are not necessarily displayed on terminal-type + displays. In GUI displays or browsers these formatting instructions are + at best ignored. + </p></div><div class="simplesect" id="id-1.10.7.4.5"><div class="titlepage"><div><div><h3 class="title">Quotation Marks</h3></div></div></div><p> + 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. + </p><p> + 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. + </p></div><div class="simplesect" id="id-1.10.7.4.6"><div class="titlepage"><div><div><h3 class="title">Use of Quotes</h3></div></div></div><p> + Always use quotes 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). + </p><p> + There are functions in the backend that will double-quote their own output + as needed (for example, <code class="function">format_type_be()</code>). Do not put + additional quotes around the output of such functions. + </p><p> + 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. + </p></div><div class="simplesect" id="id-1.10.7.4.7"><div class="titlepage"><div><div><h3 class="title">Grammar and Punctuation</h3></div></div></div><p> + The rules are different for primary error messages and for detail/hint + messages: + </p><p> + 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. + </p><p> + Detail and hint messages: Use complete sentences, and end each with + a period. Capitalize the first word of sentences. Put two spaces after + the period if another sentence follows (for English text; might be + inappropriate in other languages). + </p><p> + Error context strings: Do not capitalize the first letter and do + not end the string with a period. Context strings should normally + not be complete sentences. + </p><p> + 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 might need to include multiple sentences. For consistency, they should + follow complete-sentence style even when there's only one sentence. + </p></div><div class="simplesect" id="id-1.10.7.4.8"><div class="titlepage"><div><div><h3 class="title">Upper Case vs. Lower Case</h3></div></div></div><p> + 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. + </p><p> + Rationale: It's easier to make everything look more consistent this + way, since some messages are complete sentences and some not. + </p></div><div class="simplesect" id="id-1.10.7.4.9"><div class="titlepage"><div><div><h3 class="title">Avoid Passive Voice</h3></div></div></div><p> + Use the active voice. Use complete sentences when there is an acting + subject (<span class="quote">“<span class="quote">A could not do B</span>”</span>). Use telegram style without + subject if the subject would be the program itself; do not use + <span class="quote">“<span class="quote">I</span>”</span> for the program. + </p><p> + Rationale: The program is not human. Don't pretend otherwise. + </p></div><div class="simplesect" id="id-1.10.7.4.10"><div class="titlepage"><div><div><h3 class="title">Present vs. Past Tense</h3></div></div></div><p> + 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. + </p><p> + There is a nontrivial semantic difference between sentences of the form: +</p><pre class="programlisting"> +could not open file "%s": %m +</pre><p> +and: +</p><pre class="programlisting"> +cannot open file "%s" +</pre><p> + The first one means that the attempt to open the file failed. The + message should give a reason, such as <span class="quote">“<span class="quote">disk full</span>”</span> or + <span class="quote">“<span class="quote">file doesn't exist</span>”</span>. The past tense is appropriate because + next time the disk might not be full anymore or the file in question might + exist. + </p><p> + The second form indicates that 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. + </p><p> + 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. + </p></div><div class="simplesect" id="id-1.10.7.4.11"><div class="titlepage"><div><div><h3 class="title">Type of the Object</h3></div></div></div><p> + When citing the name of an object, state what kind of object it is. + </p><p> + Rationale: Otherwise no one will know what <span class="quote">“<span class="quote">foo.bar.baz</span>”</span> + refers to. + </p></div><div class="simplesect" id="id-1.10.7.4.12"><div class="titlepage"><div><div><h3 class="title">Brackets</h3></div></div></div><p> + Square brackets are only to be used (1) in command synopses to denote + optional arguments, or (2) to denote an array subscript. + </p><p> + Rationale: Anything else does not correspond to widely-known customary + usage and will confuse people. + </p></div><div class="simplesect" id="id-1.10.7.4.13"><div class="titlepage"><div><div><h3 class="title">Assembling Error Messages</h3></div></div></div><p> + When a message includes text that is generated elsewhere, embed it in + this style: +</p><pre class="programlisting"> +could not open file %s: %m +</pre><p> + </p><p> + 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. + </p></div><div class="simplesect" id="id-1.10.7.4.14"><div class="titlepage"><div><div><h3 class="title">Reasons for Errors</h3></div></div></div><p> + Messages should always state the reason why an error occurred. + For example: +</p><pre class="programlisting"> +BAD: could not open file %s +BETTER: could not open file %s (I/O failure) +</pre><p> + If no reason is known you better fix the code. + </p></div><div class="simplesect" id="id-1.10.7.4.15"><div class="titlepage"><div><div><h3 class="title">Function Names</h3></div></div></div><p> + 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. +</p><pre class="programlisting"> +BAD: pg_strtoint32: error in "z": cannot parse "z" +BETTER: invalid input syntax for type integer: "z" +</pre><p> + </p><p> + Avoid mentioning called function names, either; instead say what the code + was trying to do: +</p><pre class="programlisting"> +BAD: open() failed: %m +BETTER: could not open file %s: %m +</pre><p> + 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.) + </p><p> + Rationale: Users don't know what all those functions do. + </p></div><div class="simplesect" id="id-1.10.7.4.16"><div class="titlepage"><div><div><h3 class="title">Tricky Words to Avoid</h3></div></div></div><p><strong>Unable. </strong> + <span class="quote">“<span class="quote">Unable</span>”</span> is nearly the passive voice. Better use + <span class="quote">“<span class="quote">cannot</span>”</span> or <span class="quote">“<span class="quote">could not</span>”</span>, as appropriate. + </p><p><strong>Bad. </strong> + Error messages like <span class="quote">“<span class="quote">bad result</span>”</span> are really hard to interpret + intelligently. It's better to write why the result is <span class="quote">“<span class="quote">bad</span>”</span>, + e.g., <span class="quote">“<span class="quote">invalid format</span>”</span>. + </p><p><strong>Illegal. </strong> + <span class="quote">“<span class="quote">Illegal</span>”</span> stands for a violation of the law, the rest is + <span class="quote">“<span class="quote">invalid</span>”</span>. Better yet, say why it's invalid. + </p><p><strong>Unknown. </strong> + Try to avoid <span class="quote">“<span class="quote">unknown</span>”</span>. Consider <span class="quote">“<span class="quote">error: unknown + response</span>”</span>. If you don't know what the response is, how do you know + it's erroneous? <span class="quote">“<span class="quote">Unrecognized</span>”</span> is often a better choice. + Also, be sure to include the value being complained of. +</p><pre class="programlisting"> +BAD: unknown node type +BETTER: unrecognized node type: 42 +</pre><p> + </p><p><strong>Find vs. Exists. </strong> + 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 <span class="quote">“<span class="quote">find</span>”</span> 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 <span class="quote">“<span class="quote">exist</span>”</span>. Using + <span class="quote">“<span class="quote">find</span>”</span> in this case sounds weak and confuses the issue. + </p><p><strong>May vs. Can vs. Might. </strong> + <span class="quote">“<span class="quote">May</span>”</span> suggests permission (e.g., "You may borrow my rake."), + and has little use in documentation or error messages. + <span class="quote">“<span class="quote">Can</span>”</span> suggests ability (e.g., "I can lift that log."), + and <span class="quote">“<span class="quote">might</span>”</span> suggests possibility (e.g., "It might rain + today."). Using the proper word clarifies meaning and assists + translation. + </p><p><strong>Contractions. </strong> + Avoid contractions, like <span class="quote">“<span class="quote">can't</span>”</span>; use + <span class="quote">“<span class="quote">cannot</span>”</span> instead. + </p><p><strong>Non-negative. </strong> + Avoid <span class="quote">“<span class="quote">non-negative</span>”</span> as it is ambiguous + about whether it accepts zero. It's better to use + <span class="quote">“<span class="quote">greater than zero</span>”</span> or + <span class="quote">“<span class="quote">greater than or equal to zero</span>”</span>. + </p></div><div class="simplesect" id="id-1.10.7.4.17"><div class="titlepage"><div><div><h3 class="title">Proper Spelling</h3></div></div></div><p> + Spell out words in full. For instance, avoid: + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + spec + </p></li><li class="listitem"><p> + stats + </p></li><li class="listitem"><p> + parens + </p></li><li class="listitem"><p> + auth + </p></li><li class="listitem"><p> + xact + </p></li></ul></div><p> + </p><p> + Rationale: This will improve consistency. + </p></div><div class="simplesect" id="id-1.10.7.4.18"><div class="titlepage"><div><div><h3 class="title">Localization</h3></div></div></div><p> + Keep in mind that error message texts need to be translated into other + languages. Follow the guidelines in <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a> + to avoid making life difficult for translators. + </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.2. Reporting Errors Within the Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.4. Miscellaneous Coding Conventions</td></tr></table></div></body></html>
\ No newline at end of file |