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

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