No one likes software bugs
They can make businesses lose valuable production time, or even worse, data corruption. For custom software developers a single bug can be a series of headaches that starts with the initial bug report, continues through locating the source of the problem and might end when a fix is made. Or it might not. This is where smart error handling can make a big difference.
More often than not software developers get notified that “something’s wrong”, or “weird things happen when I click this button”, or “there was some kind of message but they don’t remember what it was … something about an error.” It’s tempting to think that users don’t care about us developers. But that’s not the case. The fact of the matter is that most users have no idea what information would be helpful to developers when they report a bug. All they know is that the software is keeping them from doing their job and it could be messing up their day.
Then there’s the problem with locating the source of the bug. Many developers understand the importance of testing for errors, but few actually do much to handle them in a way that provides them or the user helpful feedback.
Better options for developers
With a little bit of work up front, implementing a robust error handling system can become a standard practice in when developing apps. Let’s start with the most basic requirement.
Testing for errors
Something I’ve heard over and over in my 20+ years of developing FileMaker solutions is the importance of trapping for errors. Yet many developers do it as an afterthought and I was guilty of doing the same for years until I got tired of getting burned. A common approach that turns into a bad habit is telling yourself you’ll go back later and test for errors in places where they’ll likely occur, but that often doesn’t happen despite best intentions.
There’s not much advice I can offer here except to follow whatever system works for you to always test for errors where there’s a possibility of failure. If you don’t do that then implementing the error handling system I describe next will be like building a house without a foundation on a sand dune.
Compose useful info about the error
Simply knowing that an error code was returned while running a script is insufficient. The bare minimum information that should be returned to a developer for troubleshooting the problem is as follows:
- The current environment factors at the time of the error. Examples are the script name, layout name, user, platform, device, script parameters, privilege set, found count, open record count, etc.
- The call stack. This can be a little tricky to set up since FileMaker doesn’t give you this information natively. You have to build it yourself. I do this by building it in reverse by always returning error info to the top level script that served as the trigger, most often from a button click. The process is straightforward. As the error info is passed back from the script where the error occurred to the scripts that called it I build a list of all the scripts that error info is passed through.
- Optional – Sometimes I’ll pass back a message to the user, especially when something more than a generic error message to the user is needed. An example of when a user needs a detailed error message is when the script that’s running is processing a batch of some sort and the batch process succeeds but with exceptions due to record locking by another user. The user needs to know which ones succeeded and which ones failed so they’ll know to try running the batch on the failed ones again later.
Log the error info and notify software support
Now that useful error information is being returned to the top level script you need to log it in some way or all the excellent error info composition you just did was a waste of time. We’ve used Fogbugz to help us manage our software development projects since 2010 and we use its API to send error information automatically to it from FileMaker with the Insert From URL script step. When a bug report is submitted to it we receive a notification almost immediately (faster than the user who experienced the error can even pick up their phone to call us).
Let the user know something went wrong & support already knows
Lastly, the user needs to be informed that something went wrong. We try to keep that simple and only tell them what they need to know in plain English. Users don’t usually care about error codes or the technical details of what happened. Sharing that info with them usually makes things worse, in my opinion.
There is one thing though that you can tell users that helps boost their confidence in you, the developer. Since you’ve already logged the bug and support has been notified, let them know. It’s reassuring. It tells the person their developer is aware of the problem and will be looking into it as quickly as possible.
Some final thoughts
Script errors are the bane of app developers. They can lead to a lot stress especially when the errors occur in a “live” or “production” deployment. That’s why I continue to be a surprised when I see so few developers actually taking meaningful steps to make them as painless as possible.
Since I set out to make errors less of a pain to deal with when we took on a massive project in 2009 I’ve lowered the levels of stress and anxiety I used to get when errors would occur. Establishing the good habit of always testing for errors at likely points of failure was the big first step. Returning the call stack with other error info was another big step that was finally made easy when FileMaker gave us JSON functions.
A few custom functions we wrote make composing the error info and building the call stack a breeze for us.
Also, using a software project management tool like Fogbugz is indispensable even if you’re working solo. There are other options like Jira and Mantis that are widely used. We prefer Fogbugz because it’s what we’re used to and it fits our needs.
I did a presentation on this topic for FMDiSC (FileMaker Developers in Southern California) on 4/9/2012 that’s on YouTube. You can view it here from 00:02:50 to 01:02:00.
If setting up a powerful error handling system or integrating it with a logging system like Fogbugz is something you need some help with just reach out to us.