Give your personal scripts good error messages
Sysadmins have a habit of accumulating little personal scripts to make our lives more convenient, often things that make perfect sense to us but are too peculiar or specific to be worth installing generally. Since these are personal hacks, they're often bashed together in very casual ways; if it mostly works for us, it's good enough.
From personal experience, I now have a suggestion for these scripts: make sure that they have clear or at least comprehensible error messages, not little cryptic ones. If you do not, there will come a day when you get that cryptic error message, generally quite a long time after having written that script, and you will sit there going 'what the heck does this mean?' and scratching your head. And then you will wind up retracing and reverse-engineering your script, and that is just plain embarrassing.
This is especially important if you put in the error message about a can't-happen situation, or at least one that your script doesn't handle, because these are just the sort of things that come up a year or two after you've written the script. By the way, I strongly advocate making any personal scripts that summarize and amalgamate information explicitly check for situations that they don't handle. This saves them silently produce very wrong answers and possibly having you act on those answers.
(It's common for me to take shortcuts and make assumptions in such scripts, since after all they only have to work in our very specific environment. Of course, sometimes these aspects of our environment change and my assumptions blow up.)
A good error message is one that is clear and complete enough that you know what went wrong without remembering how the script works. Especially if it's for an error you never expect to happen, err on the side of verbosity and over-explaining things; terse error messages make sense only when you're going to see them reasonably often.
Sadly, doing this well can be harder than it looks. When you're writing a script you're immersed in what it does and how it works, so even if you think in these terms it's quite easy to over-estimate how much you'll remember six months or a year from now when you actually get that error message. Speaking from more personal experience, even rewriting the error message after you've had to retrace the script a year later doesn't entirely help, since of course now you understand the script again.
(And on that note, I should go revise an error message or two.)
Comments on this page:Written on 24 May 2010.