1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>44.3.Error Message Style Guide</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="source.html" title="Chapter44.PostgreSQL Coding Conventions">
<link rel="prev" href="error-message-reporting.html" title="44.2.Reporting Errors Within the Server">
<link rel="next" href="nls.html" title="Chapter45.Native Language Support">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="error-style-guide"></a>44.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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839650"></a>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">Short</span>” means “<span class="quote">should fit on one line under normal
conditions</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 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.
</p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839705"></a>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) 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.)
</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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839725"></a>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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839762"></a>Use of quotes</h3></div></div></div>
<p> 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).
</p>
<p> There are functions in the backend that will double-quote their own output
at need (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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839791"></a>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.
</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 may 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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839821"></a>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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839836"></a>Avoid passive voice</h3></div></div></div>
<p> Use the active voice. Use complete sentences when there is an acting
subject (“<span class="quote">A could not do B</span>”). Use telegram style without
subject if the subject would be the program itself; do not use
“<span class="quote">I</span>” for the program.
</p>
<p> Rationale: The program is not human. Don't pretend otherwise.
</p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839858"></a>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">disk full</span>” or
“<span class="quote">file doesn't exist</span>”. The past tense is appropriate because
next time the disk might not be full anymore or the file in question may
exist.
</p>
<p> 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.
</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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839912"></a>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">foo.bar.baz</span>”
refers to.
</p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839928"></a>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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839941"></a>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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839959"></a>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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id839975"></a>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_atoi: error in "z": can't parse "z"
BETTER: invalid input syntax for 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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id840014"></a>Tricky words to avoid</h3></div></div></div>
<p><b>Unable.</b> “<span class="quote">Unable</span>” is nearly the passive voice. Better use
“<span class="quote">cannot</span>” or “<span class="quote">could not</span>”, as appropriate.
</p>
<p><b>Bad.</b> Error messages like “<span class="quote">bad result</span>” are really hard to interpret
intelligently. It's better to write why the result is “<span class="quote">bad</span>”,
e.g., “<span class="quote">invalid format</span>”.
</p>
<p><b>Illegal.</b> “<span class="quote">Illegal</span>” stands for a violation of the law, the rest is
“<span class="quote">invalid</span>”. Better yet, say why it's invalid.
</p>
<p><b>Unknown.</b> Try to avoid “<span class="quote">unknown</span>”. Consider “<span class="quote">error: unknown
response</span>”. If you don't know what the response is, how do you know
it's erroneous? “<span class="quote">Unrecognized</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><b>Find vs. Exists.</b> 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">find</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">exist</span>”. Using
“<span class="quote">find</span>” in this case sounds weak and confuses the issue.
</p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id840130"></a>Proper spelling</h3></div></div></div>
<p> Spell out words in full. For instance, avoid:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p> spec
</p></li>
<li><p> stats
</p></li>
<li><p> parens
</p></li>
<li><p> auth
</p></li>
<li><p> xact
</p></li>
</ul></div>
<p>
</p>
<p> Rationale: This will improve consistency.
</p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id840163"></a>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 href="nls-programmer.html#nls-guidelines" title="45.2.2.Message-writing guidelines">Section45.2.2, “Message-writing guidelines”</a>
to avoid making life difficult for translators.
</p>
</div>
</div></body>
</html>
|
