Last Week on My Mac: Handling errors

We might like to pretend that errors never occur, but the reality is that they do even in the best-written software. What makes the difference is how those errors are handled.

This is a fine example: an icon that’s hard to recognise, a title that could mislead you to think this is about Privacy & Security, and explanatory text that is so vague as to be obtuse. After all that, it offers only one way out, to admit that it’s OK.

I’ll accept responsibility for this example from Cirrus, but at least the icon gives a clue, and the explanation tells you what didn’t work as you had expected.

Those two errors were unexpected, although both should have been anticipated. When one of the app’s purposes is to look for errors, there’s even greater responsibility for ensuring that they’re well handled.

Disk Utility has a whole scrolling text view in which to provide information, but if you’re curious enough to Show Details when First Aid fails, you could be rewarded with the same message re-expressed more inscrutably, and an error code that you won’t even find on a third-party website like OSStatus.com.

Here’s another favourite, encountered when trying to open an app with a signature problem. Its three-line title states that the app can’t be opened, but one of its three buttons reckons that it can and will open the app after all.

There are, though, many good examples of handling errors well: this one’s from Apparency, from Mothers Ruin.

I should point out that this particular code signature error is so unusual as to be a collector’s item, and the fact that Apparency handles it with aplomb should be an example to us all.

All software has a responsibility to its users to handle errors helpfully. There’s no single solution, and Apple’s interface guidelines only concern themselves with design and layout of alerts, not their content. NSError in the macOS API provides some of the underpinnings required for better error handling, but yet again no one seems to have touched its reference documentation since early 2011.

The first thing I want to know in any alert or message is the plain statement that this is an error. Call it a fault if you prefer, but euphemisms about unexpected events don’t wash with me. If neither the app nor its user was expecting that to happen, then surely that’s good enough to fess up and call it an error. This is important, as we now see so many alerts and notifications that we need to be able to classify them quickly. An error calls for my attention.

Next I need to know what exactly the error was. If there’s but a single app running on my Mac, then it might appear obvious, but when that window could have been displayed by any of a dozen different apps, knowing unequivocally which app it occurred in, and what went wrong, is essential.

We’re only half way there, though. In many cases I’m already aware that something went wrong, and may even have a good idea as to what failed. Leave me just that information, and I’m wondering what I can do about it. Here First Aid’s volume unmounting errors are a good example: I’ve learned that selecting the volume(s) that can’t be unmounted, and unmounting them manually, can solve the problem. So why not tell me that in the scrolling text view? Assuming that I’m going to open the app’s Help book and stumble about trying to locate suggestions there isn’t good enough. If the user does need to refer to more extensive information, then why not give them a clue?

In addition, in situations where the error might have more serious implications, such as loss of data, I need to know how to limit any consequential damage. Disk Utility does sometimes attempt this, in suggesting that the user backs the volume up, and has recently become more measured in making that recommendation.

Finally, I need a specific error name or code that I can refer to if I contact support to seek help. Many users now have the presence of mind to make a screenshot, but error codes that are documented can still be valuable when seeking assistance.

My summary of what I’d like when handling errors is therefore:

Confess
Identify
Solution
Damage limitation
Reference.

For many common errors, these can be rolled into just a few lines, but in some cases a more extensive approach is required. If we can enjoy that in a free app like Apparency, there’s no excuse for anything less in commercial products.