begriffs open source - ai-pg/blob - full-docs/html/error-style-guide.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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>55.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="55.2. Reporting Errors Within the Server" /><link rel="next" href="source-conventions.html" title="55.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">55.3. Error Message Style Guide</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-message-reporting.html" title="55.2. Reporting Errors Within the Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 55. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="source-conventions.html" title="55.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">55.3. Error Message Style Guide <a href="#ERROR-STYLE-GUIDE" class="id_link">#</a></h2></div></div></div><p>
   3     This style guide is offered in the hope of maintaining a consistent,
   4     user-friendly style throughout all the messages generated by
   5     <span class="productname">PostgreSQL</span>.
   6    </p><div class="simplesect" id="ERROR-STYLE-GUIDE-WHAT-GOES-WHERE"><div class="titlepage"><div><div><h3 class="title">What Goes Where <a href="#ERROR-STYLE-GUIDE-WHAT-GOES-WHERE" class="id_link">#</a></h3></div></div></div><p>
   7     The primary message should be short, factual, and avoid reference to
   8     implementation details such as specific function names.
   9     <span class="quote">“<span class="quote">Short</span>”</span> means <span class="quote">“<span class="quote">should fit on one line under normal
  10     conditions</span>”</span>.  Use a detail message if needed to keep the primary
  11     message short, or if you feel a need to mention implementation details
  12     such as the particular system call that failed. Both primary and detail
  13     messages should be factual.  Use a hint message for suggestions about what
  14     to do to fix the problem, especially if the suggestion might not always be
  15     applicable.
  16    </p><p>
  17     For example, instead of:
  18 </p><pre class="programlisting">
  19 IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
  20 (plus a long addendum that is basically a hint)
  21 </pre><p>
  22     write:
  23 </p><pre class="programlisting">
  24 Primary:    could not create shared memory segment: %m
  25 Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o).
  26 Hint:       The addendum, written as a complete sentence.
  27 </pre><p>
  28    </p><p>
  29     Rationale: keeping the primary message short helps keep it to the point,
  30     and lets clients lay out screen space on the assumption that one line is
  31     enough for error messages.  Detail and hint messages can be relegated to a
  32     verbose mode, or perhaps a pop-up error-details window.  Also, details and
  33     hints would normally be suppressed from the server log to save
  34     space. Reference to implementation details is best avoided since users
  35     aren't expected to know the details.
  36    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-FORMATTING"><div class="titlepage"><div><div><h3 class="title">Formatting <a href="#ERROR-STYLE-GUIDE-FORMATTING" class="id_link">#</a></h3></div></div></div><p>
  37     Don't put any specific assumptions about formatting into the message
  38     texts.  Expect clients and the server log to wrap lines to fit their own
  39     needs.  In long messages, newline characters (\n) can be used to indicate
  40     suggested paragraph breaks.  Don't end a message with a newline.  Don't
  41     use tabs or other formatting characters.  (In error context displays,
  42     newlines are automatically added to separate levels of context such as
  43     function calls.)
  44    </p><p>
  45     Rationale: Messages are not necessarily displayed on terminal-type
  46     displays.  In GUI displays or browsers these formatting instructions are
  47     at best ignored.
  48    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-QUOTATION-MARKS"><div class="titlepage"><div><div><h3 class="title">Quotation Marks <a href="#ERROR-STYLE-GUIDE-QUOTATION-MARKS" class="id_link">#</a></h3></div></div></div><p>
  49     English text should use double quotes when quoting is appropriate.
  50     Text in other languages should consistently use one kind of quotes that is
  51     consistent with publishing customs and computer output of other programs.
  52    </p><p>
  53     Rationale: The choice of double quotes over single quotes is somewhat
  54     arbitrary, but tends to be the preferred use.  Some have suggested
  55     choosing the kind of quotes depending on the type of object according to
  56     SQL conventions (namely, strings single quoted, identifiers double
  57     quoted).  But this is a language-internal technical issue that many users
  58     aren't even familiar with, it won't scale to other kinds of quoted terms,
  59     it doesn't translate to other languages, and it's pretty pointless, too.
  60    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-QUOTES"><div class="titlepage"><div><div><h3 class="title">Use of Quotes <a href="#ERROR-STYLE-GUIDE-QUOTES" class="id_link">#</a></h3></div></div></div><p>
  61     Always use quotes to delimit file names, user-supplied identifiers,
  62     configuration variable names, and other variables that might contain
  63     words.  Do not use them to mark up variables that will not contain words
  64     (for example, operator names).
  65    </p><p>
  66     There are functions in the backend that will double-quote their own output
  67     as needed (for example, <code class="function">format_type_be()</code>).  Do not put
  68     additional quotes around the output of such functions.
  69    </p><p>
  70     Rationale: Objects can have names that create ambiguity when embedded in a
  71     message.  Be consistent about denoting where a plugged-in name starts and
  72     ends.  But don't clutter messages with unnecessary or duplicate quote
  73     marks.
  74    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-GRAMMAR-PUNCTUATION"><div class="titlepage"><div><div><h3 class="title">Grammar and Punctuation <a href="#ERROR-STYLE-GUIDE-GRAMMAR-PUNCTUATION" class="id_link">#</a></h3></div></div></div><p>
  75     The rules are different for primary error messages and for detail/hint
  76     messages:
  77    </p><p>
  78     Primary error messages: Do not capitalize the first letter.  Do not end a
  79     message with a period.  Do not even think about ending a message with an
  80     exclamation point.
  81    </p><p>
  82     Detail and hint messages: Use complete sentences, and end each with
  83     a period.  Capitalize the first word of sentences.  Put two spaces after
  84     the period if another sentence follows (for English text; might be
  85     inappropriate in other languages).
  86    </p><p>
  87     Error context strings: Do not capitalize the first letter and do
  88     not end the string with a period.  Context strings should normally
  89     not be complete sentences.
  90    </p><p>
  91     Rationale: Avoiding punctuation makes it easier for client applications to
  92     embed the message into a variety of grammatical contexts.  Often, primary
  93     messages are not grammatically complete sentences anyway.  (And if they're
  94     long enough to be more than one sentence, they should be split into
  95     primary and detail parts.)  However, detail and hint messages are longer
  96     and might need to include multiple sentences.  For consistency, they should
  97     follow complete-sentence style even when there's only one sentence.
  98    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-CASE"><div class="titlepage"><div><div><h3 class="title">Upper Case vs. Lower Case <a href="#ERROR-STYLE-GUIDE-CASE" class="id_link">#</a></h3></div></div></div><p>
  99     Use lower case for message wording, including the first letter of a
 100     primary error message.  Use upper case for SQL commands and key words if
 101     they appear in the message.
 102    </p><p>
 103     Rationale: It's easier to make everything look more consistent this
 104     way, since some messages are complete sentences and some not.
 105    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-PASSIVE-VOICE"><div class="titlepage"><div><div><h3 class="title">Avoid Passive Voice <a href="#ERROR-STYLE-GUIDE-PASSIVE-VOICE" class="id_link">#</a></h3></div></div></div><p>
 106     Use the active voice.  Use complete sentences when there is an acting
 107     subject (<span class="quote">“<span class="quote">A could not do B</span>”</span>).  Use telegram style without
 108     subject if the subject would be the program itself; do not use
 109     <span class="quote">“<span class="quote">I</span>”</span> for the program.
 110    </p><p>
 111     Rationale: The program is not human.  Don't pretend otherwise.
 112    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-TENSE"><div class="titlepage"><div><div><h3 class="title">Present vs. Past Tense <a href="#ERROR-STYLE-GUIDE-TENSE" class="id_link">#</a></h3></div></div></div><p>
 113     Use past tense if an attempt to do something failed, but could perhaps
 114     succeed next time (perhaps after fixing some problem).  Use present tense
 115     if the failure is certainly permanent.
 116    </p><p>
 117     There is a nontrivial semantic difference between sentences of the form:
 118 </p><pre class="programlisting">
 119 could not open file "%s": %m
 120 </pre><p>
 121 and:
 122 </p><pre class="programlisting">
 123 cannot open file "%s"
 124 </pre><p>
 125     The first one means that the attempt to open the file failed.  The
 126     message should give a reason, such as <span class="quote">“<span class="quote">disk full</span>”</span> or
 127     <span class="quote">“<span class="quote">file doesn't exist</span>”</span>.  The past tense is appropriate because
 128     next time the disk might not be full anymore or the file in question might
 129     exist.
 130    </p><p>
 131     The second form indicates that the functionality of opening the named file
 132     does not exist at all in the program, or that it's conceptually
 133     impossible.  The present tense is appropriate because the condition will
 134     persist indefinitely.
 135    </p><p>
 136     Rationale: Granted, the average user will not be able to draw great
 137     conclusions merely from the tense of the message, but since the language
 138     provides us with a grammar we should use it correctly.
 139    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-OBJECT-TYPE"><div class="titlepage"><div><div><h3 class="title">Type of the Object <a href="#ERROR-STYLE-GUIDE-OBJECT-TYPE" class="id_link">#</a></h3></div></div></div><p>
 140     When citing the name of an object, state what kind of object it is.
 141    </p><p>
 142     Rationale: Otherwise no one will know what <span class="quote">“<span class="quote">foo.bar.baz</span>”</span>
 143     refers to.
 144    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-BRACKETS"><div class="titlepage"><div><div><h3 class="title">Brackets <a href="#ERROR-STYLE-GUIDE-BRACKETS" class="id_link">#</a></h3></div></div></div><p>
 145     Square brackets are only to be used (1) in command synopses to denote
 146     optional arguments, or (2) to denote an array subscript.
 147    </p><p>
 148     Rationale: Anything else does not correspond to widely-known customary
 149     usage and will confuse people.
 150    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-ERROR-MESSAGES"><div class="titlepage"><div><div><h3 class="title">Assembling Error Messages <a href="#ERROR-STYLE-GUIDE-ERROR-MESSAGES" class="id_link">#</a></h3></div></div></div><p>
 151    When a message includes text that is generated elsewhere, embed it in
 152    this style:
 153 </p><pre class="programlisting">
 154 could not open file %s: %m
 155 </pre><p>
 156    </p><p>
 157     Rationale: It would be difficult to account for all possible error codes
 158     to paste this into a single smooth sentence, so some sort of punctuation
 159     is needed.  Putting the embedded text in parentheses has also been
 160     suggested, but it's unnatural if the embedded text is likely to be the
 161     most important part of the message, as is often the case.
 162    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-ERROR-REASONS"><div class="titlepage"><div><div><h3 class="title">Reasons for Errors <a href="#ERROR-STYLE-GUIDE-ERROR-REASONS" class="id_link">#</a></h3></div></div></div><p>
 163     Messages should always state the reason why an error occurred.
 164     For example:
 165 </p><pre class="programlisting">
 166 BAD:    could not open file %s
 167 BETTER: could not open file %s (I/O failure)
 168 </pre><p>
 169     If no reason is known you better fix the code.
 170    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-FUNCTION-NAMES"><div class="titlepage"><div><div><h3 class="title">Function Names <a href="#ERROR-STYLE-GUIDE-FUNCTION-NAMES" class="id_link">#</a></h3></div></div></div><p>
 171     Don't include the name of the reporting routine in the error text. We have
 172     other mechanisms for finding that out when needed, and for most users it's
 173     not helpful information.  If the error text doesn't make as much sense
 174     without the function name, reword it.
 175 </p><pre class="programlisting">
 176 BAD:    pg_strtoint32: error in "z": cannot parse "z"
 177 BETTER: invalid input syntax for type integer: "z"
 178 </pre><p>
 179    </p><p>
 180     Avoid mentioning called function names, either; instead say what the code
 181     was trying to do:
 182 </p><pre class="programlisting">
 183 BAD:    open() failed: %m
 184 BETTER: could not open file %s: %m
 185 </pre><p>
 186     If it really seems necessary, mention the system call in the detail
 187     message.  (In some cases, providing the actual values passed to the
 188     system call might be appropriate information for the detail message.)
 189    </p><p>
 190     Rationale: Users don't know what all those functions do.
 191    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-TRICKY-WORDS"><div class="titlepage"><div><div><h3 class="title">Tricky Words to Avoid <a href="#ERROR-STYLE-GUIDE-TRICKY-WORDS" class="id_link">#</a></h3></div></div></div><p><strong>Unable. </strong>
 192     <span class="quote">“<span class="quote">Unable</span>”</span> is nearly the passive voice.  Better use
 193     <span class="quote">“<span class="quote">cannot</span>”</span> or <span class="quote">“<span class="quote">could not</span>”</span>, as appropriate.
 194    </p><p><strong>Bad. </strong>
 195     Error messages like <span class="quote">“<span class="quote">bad result</span>”</span> are really hard to interpret
 196     intelligently.  It's better to write why the result is <span class="quote">“<span class="quote">bad</span>”</span>,
 197     e.g., <span class="quote">“<span class="quote">invalid format</span>”</span>.
 198    </p><p><strong>Illegal. </strong>
 199     <span class="quote">“<span class="quote">Illegal</span>”</span> stands for a violation of the law, the rest is
 200     <span class="quote">“<span class="quote">invalid</span>”</span>. Better yet, say why it's invalid.
 201    </p><p><strong>Unknown. </strong>
 202     Try to avoid <span class="quote">“<span class="quote">unknown</span>”</span>.  Consider <span class="quote">“<span class="quote">error: unknown
 203     response</span>”</span>.  If you don't know what the response is, how do you know
 204     it's erroneous? <span class="quote">“<span class="quote">Unrecognized</span>”</span> is often a better choice.
 205     Also, be sure to include the value being complained of.
 206 </p><pre class="programlisting">
 207 BAD:    unknown node type
 208 BETTER: unrecognized node type: 42
 209 </pre><p>
 210    </p><p><strong>Find vs. Exists. </strong>
 211     If the program uses a nontrivial algorithm to locate a resource (e.g., a
 212     path search) and that algorithm fails, it is fair to say that the program
 213     couldn't <span class="quote">“<span class="quote">find</span>”</span> the resource.  If, on the other hand, the
 214     expected location of the resource is known but the program cannot access
 215     it there then say that the resource doesn't <span class="quote">“<span class="quote">exist</span>”</span>.  Using
 216     <span class="quote">“<span class="quote">find</span>”</span> in this case sounds weak and confuses the issue.
 217    </p><p><strong>May vs. Can vs. Might. </strong>
 218     <span class="quote">“<span class="quote">May</span>”</span> suggests permission (e.g., "You may borrow my rake."),
 219     and has little use in documentation or error messages.
 220     <span class="quote">“<span class="quote">Can</span>”</span> suggests ability (e.g., "I can lift that log."),
 221     and <span class="quote">“<span class="quote">might</span>”</span> suggests possibility (e.g., "It might rain
 222     today.").  Using the proper word clarifies meaning and assists
 223     translation.
 224    </p><p><strong>Contractions. </strong>
 225     Avoid contractions, like <span class="quote">“<span class="quote">can't</span>”</span>;  use
 226     <span class="quote">“<span class="quote">cannot</span>”</span> instead.
 227    </p><p><strong>Non-negative. </strong>
 228     Avoid <span class="quote">“<span class="quote">non-negative</span>”</span> as it is ambiguous
 229     about whether it accepts zero.  It's better to use
 230     <span class="quote">“<span class="quote">greater than zero</span>”</span> or
 231     <span class="quote">“<span class="quote">greater than or equal to zero</span>”</span>.
 232    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-SPELLING"><div class="titlepage"><div><div><h3 class="title">Proper Spelling <a href="#ERROR-STYLE-GUIDE-SPELLING" class="id_link">#</a></h3></div></div></div><p>
 233     Spell out words in full.  For instance, avoid:
 234   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 235      spec
 236     </p></li><li class="listitem"><p>
 237      stats
 238     </p></li><li class="listitem"><p>
 239      parens
 240     </p></li><li class="listitem"><p>
 241      auth
 242     </p></li><li class="listitem"><p>
 243      xact
 244     </p></li></ul></div><p>
 245    </p><p>
 246     Rationale: This will improve consistency.
 247    </p></div><div class="simplesect" id="ERROR-STYLE-GUIDE-LOCALIZATION"><div class="titlepage"><div><div><h3 class="title">Localization <a href="#ERROR-STYLE-GUIDE-LOCALIZATION" class="id_link">#</a></h3></div></div></div><p>
 248     Keep in mind that error message texts need to be translated into other
 249     languages.  Follow the guidelines in <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="56.2.2. Message-Writing Guidelines">Section 56.2.2</a>
 250     to avoid making life difficult for translators.
 251    </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="55.2. Reporting Errors Within the Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source-conventions.html" title="55.4. Miscellaneous Coding Conventions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.2. Reporting Errors Within the Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.4. Miscellaneous Coding Conventions</td></tr></table></div></body></html>