Get your team started on a custom learning journey today!
Our Boulder, CO-based learning experts are ready to help!
Get your team started on a custom learning journey today!
Our Boulder, CO-based learning experts are ready to help!
Follow us on LinkedIn for our latest data and tips!
Error handling is important. It’s significantly important to user experience (or in this case, developer experience) because it’s living, reactive documentation of your code. The most detailed, wiki-filled documentation can’t see your code and suggest to you why something does not work. I strongly believe that errors (often an afterthought) are part of the user/developer experience, too. This article is about writing effective error handling for developers.
I recently built a lightweight, vanilla JavaScript plugin to improve my understanding of JavaScript. It’s a responsive navigation plugin called KoalaNav and it makes menus easier to build. To complete the plugin I needed some of my peers to do a code review. One item we focused on that I did not expect was error handling and how to fail gracefully.
I had some error handling built in, but only a few reports to the console for invalid options. If an option had an invalid value the plugin would fail, but the developer could find more information in the console. My peers suggested a couple ways to improve on my error handling. The suggestions they gave could be summed up into one, simple rule:
Give developers the benefit of the doubt, but when you can’t, error gracefully.
After refactoring the plugin with their suggestions I believe this rule is fully satisfied. Here is the way I’ll approach error handling in the next plugin/application/whatever I write.
This is the first step in writing good error handling. It doesn’t do developers any good to create detailed errors for situations that rarily happen. It’s important to think about how your code could commonly break.
For example, KoalaNav is written in JavaScript and doesn’t use jQuery. I use document.getElementById
to target the navigation element. A developer may be tempted to use an ID selector with a #
at the beginning. A value like #main-navigation
would cause the document.getElementById
to fail.
Another example is KoalaNav uses an integer to determine when the navigation should swap between mobile devices and larger devices. By default this is 500
(pixels), but a developer can modify this number. What happens if they entered this value as "400px"
? It would fail because we’re looking for an integer, not a string.
These are some common errors that developers could run into with my plugin. Error handling is contextual and it’s important to think about how your code could commonly break.
Using the examples above, we could just let the code fail and throw an error to the console. The errors could be printed out as such:
KoalaNav: You used an invalid wrapper. Do not use a "#" in your selector. KoalaNav: You used an invalid value for your breakpoint. "400px" must be written as an integer.
This would certainly inform the developer of what specifically went wrong instead of failing and letting them turn to the documentation again.
Jordan Kasper, one of my peers, made a great suggestion. Rather than fail and give information why, what if we could fix this error for the developer? We do have ways to determine if strings contain specific characters and what type of variable we’re working with.
We can fix the first error if we drop the first character of the wrapper if it starts with a #
. This can be easily corrected with the following JavaScript:
// If our wrapper starts with a "#" character if (wrapper.charAt(0) === "#") { // Remove the first character in the string wrapper = wrapper.substr(1); }
Now a developer can accidentally use a jQuery-like selector without failure. We can apply that same “catch-and-fix” logic to our breakpoint option if "400px"
was provided:
// If our value is a string if (typeof mobileWidth === "string") { // setup a list of unit types that a developer might enter in var badUnits = /px|em|rem/gi; // strip out any matching units mobileWidth = mobileWidth.replace(badUnits, ""); // convert our varible back to an integer mobileWidth = parseInt(mobileWidth); }
With a little bit of code, we can take situations that would originally break our code to fix common pitfalls. This makes our code a bit more joyful to work with because we can assist the developer through potential errors.
Now that we’re catching and fixing erroneous values, it’s a good idea to educate developers on the proper way to use our code. KoalaNav takes advantage of console.warn()
to note the values provided have been altered.
Note: The console
function does not work in older browsers. Because KoalaNav supports IE 9+, we don’t need to worry about browsers that are older than this.
Here’s an example of what that looks like if we refactored our wrapper fix:
// If our wrapper starts with a "#" character if (wrapper.charAt(0) === "#") { // Store the old wrapper name for our warning message var oldWrapper = wrapper; // Remove the first character in the string wrapper = wrapper.substr(1); // Inform the developer of the conversion console.warn('You used "' + oldWrapper + '", a jQuery-like selector for your menu selector. This must be written without the "#" and has been converted to "' + wrapper + '" for you.'); }
Now we’re fixing the error for the developer and also giving them information on what is happening to their code when the wrapper value is intercepted and modified.
If our plugin broke because of a bad value and we didn’t provide more details, we’d send the developer back to wiki-laden documentation and they could still miss why it isn’t working. The worst case is they get tired, give up, and use another library/plugin/etc.
This is what I mean when I use the term “reactive documentation”. Our codebase is reacting to what the developer is doing and teaching them as they use it – even if the code is being used incorrectly.
There are always going to be times where you can’t anticipate how your code will break.
For example, KoalaNav has an option to change if the mobile toggle button displays on the left or the right side. This means there are only two values available for this option: btnPosition: "left"
or btnPosition: "right"
. So what happens if a developer tries to use btnPosition: "middle"
or btnPosition: 500
? Sometimes you must resolve to a sensible default value.
Here’s what the error handling looks like for this case:
// Is btnPosition set to "left" or "right"? if (btnPosition !== 'left' && btnPosition !== 'right') { // If not, warn the developer console.warn('You did not enter a valid btnPosition argument on #' + wrapper + '. You used "' + btnPosition + '" instead. ' + 'Now using the default btnPosition value.'); // Set btnPosition to the default value, "left" btnPosition = 'left'; }
Because we can’t give the developer the benefit of the doubt, we’ll error gracefully. This allows the plugin to function, but the default value is used in place of an invalid value.
Building this plugin helped me understand the value of good error handling. Most developers didn’t invest the time into my code like I did. It’s important that a developer gets educated (in our case, on-the-fly) as they use our code. Write as much helpful reactive documentation as you can.
Customized Technical Learning Solutions to Help Attract and Retain Talented Developers
Let DI help you design solutions to onboard, upskill or reskill your software development organization. Fully customized. 100% guaranteed.
DevelopIntelligence leads technical and software development learning programs for Fortune 500 companies. We provide learning solutions for hundreds of thousands of engineers for over 250 global brands.
“I appreciated the instructor’s technique of writing live code examples rather than using fixed slide decks to present the material.”
VMwareDevelopIntelligence has been in the technical/software development learning and training industry for nearly 20 years. We’ve provided learning solutions to more than 48,000 engineers, across 220 organizations worldwide.
Thank you for everyone who joined us this past year to hear about our proven methods of attracting and retaining tech talent.
© 2013 - 2022 DevelopIntelligence LLC - Privacy Policy
Let's review your current tech training programs and we'll help you baseline your success against some of our big industry partners. In this 30-minute meeting, we'll share our data/insights on what's working and what's not.
Training Journal sat down with our CEO for his thoughts on what’s working, and what’s not working.