code, musings and more tag:blog.netherlabs.nl,2005:Typo Typo 2006-09-08T16:48:12+02:00 bert hubert bert.hubert@netherlabs.nl urn:uuid:34c6bf3d-0bc1-4c52-84c7-65b39cdf8b6e 2006-09-08T15:36:00+02:00 2006-09-08T16:48:12+02:00

<p>Programming is a lot of things. One of them is writing good error messages. We tend to think that errors are rare and this should of course be so. However, sometimes they are not, and in that case, good reporting is vital to quickly resolve the problem.</p> <p>So, even though we should make sure errors do not happen, if they do, our error messages should be top notch.</p> <h1>About error messages</h1> <h2>Purpose </h2> <ul> <li><p>For operators, they are vital aids in configuring software</p></li> <li><p>For system adminstrators, they show which external problems need to be resolved (disk full, network down, etc).</p></li> <li><p>Should a program crash, the authors often only have error messages as clues to why this happened. Many crashes are preceded by errors that are reported. A good error can help generate a bug fix.</p></li> </ul> <h2>Taxonomy of error messages</h2> <ol> <li>Configuration problems, for example, looking for a file in directory A while it resides in directory B;</li> <li>Unavailable resources (disk full, out of memory), connectivity problems;</li> <li>Should Never Happen.</li> </ol> <h2>Configuration problems</h2> <p>These commonly occur while software is being installed and setup. Good error reporting is of utmost importance here, as it serves two purposes:</p> <ol> <li>Educating the operator about how the program functions;</li> <li>Explaining what needs to be fixed.</li> </ol> <p>Ad 1, an error like &#8220;Can&#8217;t start frobnicator because the discombulator is not running&#8221; teaches the operator that a frobnicator needs a discombulator. This knowledge can of course also be gleened from the documentation, but in this case, repetition is a good thing. </p> <p>Compare this error to &#8220;Can&#8217;t start process: Connection refused&#8221;, for example, and think about how helpful that is.</p> <p>Ad 2, a report like &#8220;Can&#8217;t connect to product database using connection string &#8216;dbuser=john, dbname=changeme&#8217;: No such database&#8221; immediately tells the operator what he needs to know.</p> <h2>Unavailable resources</h2> <p>These typically occur while a program is already running and installed, but are nonetheless important. Do not log &#8216;Disk full&#8217;, but report &#8216;Disk full writing to &#8230;.&#8217; so the operator knows which disk filled up. If a server could not be reached, log the IP address and possibly the name of the server. Any discrepancy between the two may point out a DNS configuration error.</p> <p>Out of memory is typically very hard to deal with, except when something really odd was going on. A typical example is trying to allocate a ridiculous amount of memory because of an earlier error, in which case logging what memory was being allocated for might help debug the problem. It typically will not help the user of a program.</p> <h2>Should never happen</h2> <p>These are errors of the program itself. Programmers quite often test for impossible conditions, especially if they sense these might conceivably happen one day. An example might be a module that can only connect to IPv4 servers that gets confronted by an IPv6 socket, which in turn leads calls to determine the IPv4 remote address to fail. </p> <p>It is tempting to be quite rude in these messages, or say stuff like &#8220;should never happen!!&#8221;, but resist these urges. One day a &#8216;should not happen&#8217; error is going to be a vital debugging clue. These errors are rare, but it pays to go, well, the extra few yards to perhaps report &#8220;unexpected address family accepting connection!&#8221;.</p> <h1>Guidelines</h1> <p>An error message should contain:</p> <ol> <li>Who is reporting the error (which subsystem, which program, which module)</li> <li>The action that failed</li> <li>The subject of the action (a directory, a server, a port number, an IP address)</li> <li>As good an indication of the actual error as possible.</li> <li>Optional - what the program is doing about it</li> </ol> <p>An excellent error message is:</p> <p><code>Webserver can't serve page, error opening file '/var/www/index.html': Permission denied, reporting HTTP 404 error</code></p> <p>Ad 1, it is tempting to include filenames, function names, and line numbers here. OpenSSL does this a lot, for example. However, almost none of your intended audience will be able to extract useful information from the fact that the error occurred on line 123 of &#8216;multiplexer.c&#8217;. Make sure the module means something to the operator. It may be as simple as the name of your program.</p> <p>Ad 2, this helps the operator determine if this error might be the explanation of observed problems. An error like &#8220;Webserver failed to increase TCP buffer size, continuing with default&#8221; can immediately be ruled out as an explanation for why people can&#8217;t log in to their mail.</p> <p>Ad 3, an error like &#8220;Can&#8217;t open file&#8221; on its own can mean many things. One of which might be that it is not reading the configuration file you think it is, and trying to open your index.html in &#8216;/usr/local/www&#8217;, and not in &#8216;/var/www&#8217; like you thought you configured. </p> <p>Ad 4, self explanatory. Take the trouble to convert error codes into strings. Many programmers may know what &#8216;errno = 111&#8217; means &#8216;Connection refused&#8217;, but don&#8217;t count on your users knowing this.</p> <p>Ad 5, this is a fine counterpoint to item 4. &#8220;Giving a 404&#8221; is very clear for any operator of a web server. Not all errors need a followup, so reporting what the program is doing about the error is not mandatory.</p> <h1>Conclusion</h1> <p>Good error messages can save your users many days of problems. And, suprisingly, you might yourself gain even more time - how well do you know the internals of your program after a few months? </p> <p>So please please, both as a user and a progammer, I ask you, spend time on error messages!</p>

<p>Programming is a lot of things. One of them is writing good error messages. We tend to think that errors are rare and this should of course be so. However, sometimes they are not, and in that case, good reporting is vital to quickly resolve the problem.</p> <p>So, even though we should make sure errors do not happen, if they do, our error messages should be top notch.</p> <h1>About error messages</h1> <h2>Purpose </h2> <ul> <li><p>For operators, they are vital aids in configuring software</p></li> <li><p>For system adminstrators, they show which external problems need to be resolved (disk full, network down, etc).</p></li> <li><p>Should a program crash, the authors often only have error messages as clues to why this happened. Many crashes are preceded by errors that are reported. A good error can help generate a bug fix.</p></li> </ul> <h2>Taxonomy of error messages</h2> <ol> <li>Configuration problems, for example, looking for a file in directory A while it resides in directory B;</li> <li>Unavailable resources (disk full, out of memory), connectivity problems;</li> <li>Should Never Happen.</li> </ol> <h2>Configuration problems</h2> <p>These commonly occur while software is being installed and setup. Good error reporting is of utmost importance here, as it serves two purposes:</p> <ol> <li>Educating the operator about how the program functions;</li> <li>Explaining what needs to be fixed.</li> </ol> <p>Ad 1, an error like &#8220;Can&#8217;t start frobnicator because the discombulator is not running&#8221; teaches the operator that a frobnicator needs a discombulator. This knowledge can of course also be gleened from the documentation, but in this case, repetition is a good thing. </p> <p>Compare this error to &#8220;Can&#8217;t start process: Connection refused&#8221;, for example, and think about how helpful that is.</p> <p>Ad 2, a report like &#8220;Can&#8217;t connect to product database using connection string &#8216;dbuser=john, dbname=changeme&#8217;: No such database&#8221; immediately tells the operator what he needs to know.</p> <h2>Unavailable resources</h2> <p>These typically occur while a program is already running and installed, but are nonetheless important. Do not log &#8216;Disk full&#8217;, but report &#8216;Disk full writing to &#8230;.&#8217; so the operator knows which disk filled up. If a server could not be reached, log the IP address and possibly the name of the server. Any discrepancy between the two may point out a DNS configuration error.</p> <p>Out of memory is typically very hard to deal with, except when something really odd was going on. A typical example is trying to allocate a ridiculous amount of memory because of an earlier error, in which case logging what memory was being allocated for might help debug the problem. It typically will not help the user of a program.</p> <h2>Should never happen</h2> <p>These are errors of the program itself. Programmers quite often test for impossible conditions, especially if they sense these might conceivably happen one day. An example might be a module that can only connect to IPv4 servers that gets confronted by an IPv6 socket, which in turn leads calls to determine the IPv4 remote address to fail. </p> <p>It is tempting to be quite rude in these messages, or say stuff like &#8220;should never happen!!&#8221;, but resist these urges. One day a &#8216;should not happen&#8217; error is going to be a vital debugging clue. These errors are rare, but it pays to go, well, the extra few yards to perhaps report &#8220;unexpected address family accepting connection!&#8221;.</p> <h1>Guidelines</h1> <p>An error message should contain:</p> <ol> <li>Who is reporting the error (which subsystem, which program, which module)</li> <li>The action that failed</li> <li>The subject of the action (a directory, a server, a port number, an IP address)</li> <li>As good an indication of the actual error as possible.</li> <li>Optional - what the program is doing about it</li> </ol> <p>An excellent error message is:</p> <p><code>Webserver can't serve page, error opening file '/var/www/index.html': Permission denied, reporting HTTP 404 error</code></p> <p>Ad 1, it is tempting to include filenames, function names, and line numbers here. OpenSSL does this a lot, for example. However, almost none of your intended audience will be able to extract useful information from the fact that the error occurred on line 123 of &#8216;multiplexer.c&#8217;. Make sure the module means something to the operator. It may be as simple as the name of your program.</p> <p>Ad 2, this helps the operator determine if this error might be the explanation of observed problems. An error like &#8220;Webserver failed to increase TCP buffer size, continuing with default&#8221; can immediately be ruled out as an explanation for why people can&#8217;t log in to their mail.</p> <p>Ad 3, an error like &#8220;Can&#8217;t open file&#8221; on its own can mean many things. One of which might be that it is not reading the configuration file you think it is, and trying to open your index.html in &#8216;/usr/local/www&#8217;, and not in &#8216;/var/www&#8217; like you thought you configured. </p> <p>Ad 4, self explanatory. Take the trouble to convert error codes into strings. Many programmers may know what &#8216;errno = 111&#8217; means &#8216;Connection refused&#8217;, but don&#8217;t count on your users knowing this.</p> <p>Ad 5, this is a fine counterpoint to item 4. &#8220;Giving a 404&#8221; is very clear for any operator of a web server. Not all errors need a followup, so reporting what the program is doing about the error is not mandatory.</p> <h1>Conclusion</h1> <p>Good error messages can save your users many days of problems. And, suprisingly, you might yourself gain even more time - how well do you know the internals of your program after a few months? </p> <p>So please please, both as a user and a progammer, I ask you, spend time on error messages!</p> 8th street latinas urn:uuid:dcbb8bca-cd94-427f-9ace-ec00acca6822 2007-05-25T09:46:22+02:00 2007-05-25T09:46:22+02:00 Try validator.w3.org should help ass parade urn:uuid:61ae9de6-8932-4730-8c45-a7a174043230 2007-05-24T23:35:38+02:00 2007-05-24T23:35:38+02:00 Recommend me please some validator, so that i could optimize my html! crissy moran urn:uuid:9b2ecd5c-11a9-4204-b3bd-fbae833dae58 2007-05-24T14:19:29+02:00 2007-05-24T14:19:29+02:00 i want to ask if it is possible to create different mysql base and keep there old not needed messages? sky lopez urn:uuid:94176563-166f-42f2-af71-00576b3a0b85 2007-05-24T00:21:22+02:00 2007-05-24T00:21:22+02:00 Programming is so exciting, you should definetely try it! tera patrick urn:uuid:3877f94f-9853-4c7e-95a3-4dff8a6ae742 2007-05-23T13:28:33+02:00 2007-05-23T13:28:33+02:00 Common mistake is not checking just created sites in all possible browsers, in order to see everything is correct! round and brown urn:uuid:c07521c5-a1bc-4e5a-a5bb-63590c5b51b0 2007-05-23T01:44:24+02:00 2007-05-23T01:44:24+02:00 Advice me please mass podcast site for free usage milf hunter urn:uuid:770f8b94-4123-4b3f-9ea5-ee1f1aa8147b 2007-05-22T13:56:16+02:00 2007-05-22T13:56:16+02:00 I am curious how do you manage all posts? is there a html editor fur ruby or rails? big naturals urn:uuid:be528a89-2968-4ac1-9ead-1b9e5a8af852 2007-05-21T14:04:56+02:00 2007-05-21T14:04:56+02:00 How to set up RSS of blogs on ruby? raven riley urn:uuid:2e550f81-6795-4259-b9bb-b864f44d38b7 2007-05-18T18:48:29+02:00 2007-05-18T18:48:29+02:00 For normal matrix degenerate own values is the freedom to define the eigenvector corresponding quaternion own values related to the replacement of any linear combination! Jenna Haze urn:uuid:7191610e-f923-4426-a8f0-7cca0d99f281 2007-05-16T18:13:38+02:00 2007-05-16T18:13:38+02:00 it's so hard nowadays to find some original admin tools for blogs that are free to use, can anyone advice any to form multi language posts? we live together urn:uuid:4c61dd07-06ed-439c-bdff-7b363c996da5 2007-05-09T17:04:11+02:00 2007-05-09T17:04:11+02:00 Predicted values in template editing can be done through any PHP script? ashish urn:uuid:38a47437-a412-4eb1-a732-3d7751af2bb7 2006-12-21T08:42:57+01:00 2006-12-21T08:42:57+01:00 Below link provide a new way to generate and manage error messages. <a href="http://www.conman.org/projects/essays/magicnum.html">http://www.conman.org/projects/essays/magicnum.html</a>