Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
error-style-guide.html250 linesDownload Raw Back to 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>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 16.3 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 <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 by5    <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 to8    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 normal10    conditions</span>”</span>.  Use a detail message if needed to keep the primary11    message short, or if you feel a need to mention implementation details12    such as the particular system call that failed. Both primary and detail13    messages should be factual.  Use a hint message for suggestions about what14    to do to fix the problem, especially if the suggestion might not always be15    applicable.16   </p><p>17    For example, instead of:18</p><pre class="programlisting">19IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m20(plus a long addendum that is basically a hint)21</pre><p>22    write:23</p><pre class="programlisting">24Primary:    could not create shared memory segment: %m25Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o).26Hint:       the addendum27</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 is31    enough for error messages.  Detail and hint messages can be relegated to a32    verbose mode, or perhaps a pop-up error-details window.  Also, details and33    hints would normally be suppressed from the server log to save34    space. Reference to implementation details is best avoided since users35    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 message38    texts.  Expect clients and the server log to wrap lines to fit their own39    needs.  In long messages, newline characters (\n) can be used to indicate40    suggested paragraph breaks.  Don't end a message with a newline.  Don't41    use tabs or other formatting characters.  (In error context displays,42    newlines are automatically added to separate levels of context such as43    function calls.)44   </p><p>45    Rationale: Messages are not necessarily displayed on terminal-type46    displays.  In GUI displays or browsers these formatting instructions are47    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 is51    consistent with publishing customs and computer output of other programs.52   </p><p>53    Rationale: The choice of double quotes over single quotes is somewhat54    arbitrary, but tends to be the preferred use.  Some have suggested55    choosing the kind of quotes depending on the type of object according to56    SQL conventions (namely, strings single quoted, identifiers double57    quoted).  But this is a language-internal technical issue that many users58    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, and62    other variables that might contain words.  Do not use them to mark up63    variables that will not contain words (for example, operator names).64   </p><p>65    There are functions in the backend that will double-quote their own output66    as needed (for example, <code class="function">format_type_be()</code>).  Do not put67    additional quotes around the output of such functions.68   </p><p>69    Rationale: Objects can have names that create ambiguity when embedded in a70    message.  Be consistent about denoting where a plugged-in name starts and71    ends.  But don't clutter messages with unnecessary or duplicate quote72    marks.73   </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>74    The rules are different for primary error messages and for detail/hint75    messages:76   </p><p>77    Primary error messages: Do not capitalize the first letter.  Do not end a78    message with a period.  Do not even think about ending a message with an79    exclamation point.80   </p><p>81    Detail and hint messages: Use complete sentences, and end each with82    a period.  Capitalize the first word of sentences.  Put two spaces after83    the period if another sentence follows (for English text; might be84    inappropriate in other languages).85   </p><p>86    Error context strings: Do not capitalize the first letter and do87    not end the string with a period.  Context strings should normally88    not be complete sentences.89   </p><p>90    Rationale: Avoiding punctuation makes it easier for client applications to91    embed the message into a variety of grammatical contexts.  Often, primary92    messages are not grammatically complete sentences anyway.  (And if they're93    long enough to be more than one sentence, they should be split into94    primary and detail parts.)  However, detail and hint messages are longer95    and might need to include multiple sentences.  For consistency, they should96    follow complete-sentence style even when there's only one sentence.97   </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>98    Use lower case for message wording, including the first letter of a99    primary error message.  Use upper case for SQL commands and key words if100    they appear in the message.101   </p><p>102    Rationale: It's easier to make everything look more consistent this103    way, since some messages are complete sentences and some not.104   </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>105    Use the active voice.  Use complete sentences when there is an acting106    subject (<span class="quote">“<span class="quote">A could not do B</span>”</span>).  Use telegram style without107    subject if the subject would be the program itself; do not use108    <span class="quote">“<span class="quote">I</span>”</span> for the program.109   </p><p>110    Rationale: The program is not human.  Don't pretend otherwise.111   </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>112    Use past tense if an attempt to do something failed, but could perhaps113    succeed next time (perhaps after fixing some problem).  Use present tense114    if the failure is certainly permanent.115   </p><p>116    There is a nontrivial semantic difference between sentences of the form:117</p><pre class="programlisting">118could not open file "%s": %m119</pre><p>120and:121</p><pre class="programlisting">122cannot open file "%s"123</pre><p>124    The first one means that the attempt to open the file failed.  The125    message should give a reason, such as <span class="quote">“<span class="quote">disk full</span>”</span> or126    <span class="quote">“<span class="quote">file doesn't exist</span>”</span>.  The past tense is appropriate because127    next time the disk might not be full anymore or the file in question might128    exist.129   </p><p>130    The second form indicates that the functionality of opening the named file131    does not exist at all in the program, or that it's conceptually132    impossible.  The present tense is appropriate because the condition will133    persist indefinitely.134   </p><p>135    Rationale: Granted, the average user will not be able to draw great136    conclusions merely from the tense of the message, but since the language137    provides us with a grammar we should use it correctly.138   </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>139    When citing the name of an object, state what kind of object it is.140   </p><p>141    Rationale: Otherwise no one will know what <span class="quote">“<span class="quote">foo.bar.baz</span>”</span>142    refers to.143   </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>144    Square brackets are only to be used (1) in command synopses to denote145    optional arguments, or (2) to denote an array subscript.146   </p><p>147    Rationale: Anything else does not correspond to widely-known customary148    usage and will confuse people.149   </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>150   When a message includes text that is generated elsewhere, embed it in151   this style:152</p><pre class="programlisting">153could not open file %s: %m154</pre><p>155   </p><p>156    Rationale: It would be difficult to account for all possible error codes157    to paste this into a single smooth sentence, so some sort of punctuation158    is needed.  Putting the embedded text in parentheses has also been159    suggested, but it's unnatural if the embedded text is likely to be the160    most important part of the message, as is often the case.161   </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>162    Messages should always state the reason why an error occurred.163    For example:164</p><pre class="programlisting">165BAD:    could not open file %s166BETTER: could not open file %s (I/O failure)167</pre><p>168    If no reason is known you better fix the code.169   </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>170    Don't include the name of the reporting routine in the error text. We have171    other mechanisms for finding that out when needed, and for most users it's172    not helpful information.  If the error text doesn't make as much sense173    without the function name, reword it.174</p><pre class="programlisting">175BAD:    pg_strtoint32: error in "z": cannot parse "z"176BETTER: invalid input syntax for type integer: "z"177</pre><p>178   </p><p>179    Avoid mentioning called function names, either; instead say what the code180    was trying to do:181</p><pre class="programlisting">182BAD:    open() failed: %m183BETTER: could not open file %s: %m184</pre><p>185    If it really seems necessary, mention the system call in the detail186    message.  (In some cases, providing the actual values passed to the187    system call might be appropriate information for the detail message.)188   </p><p>189    Rationale: Users don't know what all those functions do.190   </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>191    <span class="quote">“<span class="quote">Unable</span>”</span> is nearly the passive voice.  Better use192    <span class="quote">“<span class="quote">cannot</span>”</span> or <span class="quote">“<span class="quote">could not</span>”</span>, as appropriate.193   </p><p><strong>Bad. </strong>194    Error messages like <span class="quote">“<span class="quote">bad result</span>”</span> are really hard to interpret195    intelligently.  It's better to write why the result is <span class="quote">“<span class="quote">bad</span>”</span>,196    e.g., <span class="quote">“<span class="quote">invalid format</span>”</span>.197   </p><p><strong>Illegal. </strong>198    <span class="quote">“<span class="quote">Illegal</span>”</span> stands for a violation of the law, the rest is199    <span class="quote">“<span class="quote">invalid</span>”</span>. Better yet, say why it's invalid.200   </p><p><strong>Unknown. </strong>201    Try to avoid <span class="quote">“<span class="quote">unknown</span>”</span>.  Consider <span class="quote">“<span class="quote">error: unknown202    response</span>”</span>.  If you don't know what the response is, how do you know203    it's erroneous? <span class="quote">“<span class="quote">Unrecognized</span>”</span> is often a better choice.204    Also, be sure to include the value being complained of.205</p><pre class="programlisting">206BAD:    unknown node type207BETTER: unrecognized node type: 42208</pre><p>209   </p><p><strong>Find vs. Exists. </strong>210    If the program uses a nontrivial algorithm to locate a resource (e.g., a211    path search) and that algorithm fails, it is fair to say that the program212    couldn't <span class="quote">“<span class="quote">find</span>”</span> the resource.  If, on the other hand, the213    expected location of the resource is known but the program cannot access214    it there then say that the resource doesn't <span class="quote">“<span class="quote">exist</span>”</span>.  Using215    <span class="quote">“<span class="quote">find</span>”</span> in this case sounds weak and confuses the issue.216   </p><p><strong>May vs. Can vs. Might. </strong>217    <span class="quote">“<span class="quote">May</span>”</span> suggests permission (e.g., "You may borrow my rake."),218    and has little use in documentation or error messages.219    <span class="quote">“<span class="quote">Can</span>”</span> suggests ability (e.g., "I can lift that log."),220    and <span class="quote">“<span class="quote">might</span>”</span> suggests possibility (e.g., "It might rain221    today.").  Using the proper word clarifies meaning and assists222    translation.223   </p><p><strong>Contractions. </strong>224    Avoid contractions, like <span class="quote">“<span class="quote">can't</span>”</span>;  use225    <span class="quote">“<span class="quote">cannot</span>”</span> instead.226   </p><p><strong>Non-negative. </strong>227    Avoid <span class="quote">“<span class="quote">non-negative</span>”</span> as it is ambiguous228    about whether it accepts zero.  It's better to use229    <span class="quote">“<span class="quote">greater than zero</span>”</span> or230    <span class="quote">“<span class="quote">greater than or equal to zero</span>”</span>.231   </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>232    Spell out words in full.  For instance, avoid:233  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>234     spec235    </p></li><li class="listitem"><p>236     stats237    </p></li><li class="listitem"><p>238     parens239    </p></li><li class="listitem"><p>240     auth241    </p></li><li class="listitem"><p>242     xact243    </p></li></ul></div><p>244   </p><p>245    Rationale: This will improve consistency.246   </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>247    Keep in mind that error message texts need to be translated into other248    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>249    to avoid making life difficult for translators.250   </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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.4. Miscellaneous Coding Conventions</td></tr></table></div></body></html>