umonya_notes/writing_errors.html at master · JHSaunders/umonya_notes · GitHub

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
<!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>
	<title>Introductory Programming in Python: Writing Meaningful Error Messages</title>
	<link rel='stylesheet' type='text/css' href='style.css' />
	<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
	<script src="animation.js" type="text/javascript">
	</script>
</head>

<body onload="animate_loop()">
	<div class="page">

		<h1>Introductory Programming in Python: Lesson 23<br />

		Writing Meaningful Error Messages</h1>

		<div class="centered">
			[<a href="datetime.html">Prev: Handling Dates and Times</a>]&nbsp;[<a href="index.html">Course Outline</a>]&nbsp;[<a href="understanding_errors.html">Next: Understanding Python's Error Messages</a>]
		</div>

		<h2>Classes of Errors: The Not So Bad, The Bad, and The UGLY</h2>

		<p>In the course of execution your program may encounter a variety of
		errors, caused by any number of things. These errors can be generally
		divided into three classes. The first class is the not so bad class,
		and includes errors that can be easily predicted <strong>and
		corrected</strong> once detected. For example, a user enters an
		alphabetic string when they were asked for a number. This can be
		checked for, and if the wrong input is given, more input can be
		requested to correct the problem.</p>

		<p>The second class of errors are those errors that can be detected,
		but not corrected, and thus require the immediate aborting of the
		current 'action' or even of the entire program. The fact that they can
		be detected, and more importantly predicted, in the sense we know there
		is a likelihood of a particular error occurring, means we can write
		programs that recover from these errors with reasonable grace. An
		example of such an error might be requesting the name of a file to be
		read from disk, checking the file exists before opening it, opening the
		file ... at this point we have passed a point of no return, we can no
		longer 'correct' any errors relating to this file ... and reading. But
		the file is incomplete! We expect to read in some sequence data, but
		only the title line in the FastA file is there. Because we can predict
		that such a situation might occur, we can write our program to recover
		from the error, by clearing any data it did read, and printing a
		message that the file was not valid, and returning the user to the
		point they were at just prior to choosing that particular file.</p>

		<p>The down right uglies of the error world are known as the
		<strong>fatal errors</strong> So named because they are fatal to our
		programs causing them to terminate immediately, not even giving the
		user a chance to save or otherwise correct the situation. Fatal errors
		are normally caused by hardware 'faults', like trying to read from a
		flash disk, and the user pulls it out mid read. But most often, fatal
		errors indicate bugs in our programs. Many fatal errors can be
		downgraded to 'not so bad' or 'bad' errors quite easily. For example,
		attempting to index a list beyond its range is a fatal error, but a
		simple check to see if the value used as the index is within the range
		of the list makes this a 'not so bad' error.</p>

		<h2>How To Handle Errors</h2>

		<p>The general way to handle errors is to alert the user, usually by a
		printed message or pop-up window, and either give them the opportunity
		to correct the conditions that caused the error, or return them to the
		point they were at prior to causing those conditions. But what message
		should we tell them... Well, let's first look at bad error
		messages!</p>

		<ol>
			<li>PC Load Letter</li>

			<li>Error: An Error has Occurred</li>

			<li>General Protection Fault at 0xF89DEX037B</li>

			<li>Error: The operation completed successfully</li>

			<li>Syntax Error Unexpected ';' on line 43 of file 'test.php'</li>
		</ol>

		<p>We can look at the top four and laugh. But we can also learn. The
		reason these are bad error messages is that they do not tell anyone (in
		a layman understandable way) what has gone wrong. The fifth would
		normally be a very good error message, except if it's
		<strong>wrong</strong>, for example if there were no ';' on line 43.
		This happens more regularly than you might think, usually because
		output of the error message has been delayed and the original cause of
		the error lost in mists of time.</p>

		<p>We have to understand that error messages are produced for different
		reasons, and for different people. Error messages that are technical
		and verbose often help us debug our own code whilst we are writing it,
		but for those error messages the user is likely to see (file does not
		exist, invalid input, etc...) we are writing for a different audience.
		So when writing error messages (and you should be writing them a lot)
		remember</p>

		<ul>

			<li>Describe the problem accurately and completely.</li>

			<li>Make sure there is in fact a problem (not as in [4] above)</li>

			<li>Tailor the error message to the level of person likely to be
			reading it, either end user, or programmer</li>

		</ul>

		<h2>Exercises</h2>

		<div class="centered">
			[<a href="datetime.html">Prev: Handling Dates and Times</a>]&nbsp;[<a href="index.html">Course Outline</a>]&nbsp;[<a href="understanding_errors.html">Next: Understanding Python's Error Messages</a>]
		</div>
	</div>

	<div class="pagefooter">
		Copyright &copy; James Dominy 2007-2008; Released under the <a href="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</a><br />
		<a href="intropython.tar.gz">Download the tarball</a>
	</div>
</body>
</html>