Functions Should Not Fail Silently

If there’s one thing a function should do it’s return a value (except for void functions but that’s another talk for another day). Whether that’s an error object or something else doesn’t matter. When we call functions we expect responses from them so when a function like jQuery’s getJSON mysteriously fails to fire off it’s callback it can be a frustrating, long process to debug.

In my latest role as a programming instructor I’ve noticed a behavior common to every student and most people learning to program from someone else (be it a video course or in person class): they want to blame someone for their errors. They’re convinced they did everything right and you came along, showed them the right or better way to do something and now their code doesn’t work. Their frustration is projected onto the instructor instead of immersed in debugging. Unless the instructor is not fit to teach the issue isn’t their fault.

This has happened with literally every student I’ve worked with and I don’t get offended by it. It’s par for the course. We always fix the issue and it’s almost always programmer error. So today my students and I came across an issue with jQuery’s getJSON method where the callback wouldn’t fire and of course it was my fault for trying to debug the code.

How the teacher breaks your code

For some context, the students initially asked for help merging their Git branches. I guided them through it and suddenly the app stopped working. So of course we looked for merge conflicts and then ran through the source code of the running app, tracing the data flow from input to final page rendering. When we found this issue we looked at the logic in our front-end JS files and found absolutely no errors. No syntax errors, nothing. Not even the console threw an error. Somehow, after merging the two students’ – who’d been pair programming on the same project – branches into master their AJAX request from a single view stopped working.

I worked on this for a good twenty minutes before I almost gave up and took a walk to clear my head. Side note: when you get stuck, take some time away from the problem. It helps clear the mind and that rest will get your mind off it’s one-track line of thought and possibly bring forth a solution. So after a break I looked at the docs for jQuery’s getJSON method for the fifth time. This time I read the entire page top to bottom and guess what I found? getJSON will silently fail if there are any errors!

Silently failing methods are bullshit

Silent failure is bullshit. An error should always be thrown when something goes wrong. Now, I think ActiveRecord’s RecordNotFound error handling for it’s find vs. find_by is ridiculous. It causes a fatal error in one scenario and returns nil in another and the whole app crashes if you’re not aware of this but at least there’s a way to anticipate and handle the error. I’m not a fan of that sort of error handling but in JS I expect a callback to accept both an error and result argument. We check for the error condition and handle it accordingly otherwise we use our result in code.

So after reading the entire page on getJSON I learned that it silently fails when it encounters invalid JSON. Not cool. I asked the students what they last did before merging. They replied “we just added comments to our JavaScript”. Comments shouldn’t cause any errors… unless they’re in a JSON file which is what they failed to mention. JSON is not JavaScript but as far as a student is concerned there’s not a whole lot of difference. JSON seems like an object written as a string so I can see how they’d think the same rules applied to JSON as they do with JavaScript’s POJOS (plain old JavaScript objects). After noticing they were calling a static JSON file I was about to run it through the JSON Pretty Print app. As we all know the JSON Pretty Print app will throw an error if you give it invalid JSON. Before I could open a browser and type in the URL I checked the JSON file and noticed they had tried to add comments to the JSON file. Error identified. A very easy error to identify. JSON files cannot contain Javascript style comments unless you’re using a special library and the Hjson syntax.

In the end we tracked down the issue to two problems:

  1. jQuery’s getJSON method fails silently
  2. Their JSON had comments was therefore invalid
  3. No one bothered to read the docs

Methods should not fail silently

There are always exceptions to a rule but when you break with tradition there should be a good reason for it. I don’t see a good reason for a jQuery AJAX shortcut function to fail silently.

The lesson learned

The people who work on the jQuery project aren’t novices. They know what they’re doing and are much smarter than me. Maybe they did have a good reason let it fail silently but I just don’t see it or agree with it.

The lesson learned here is that you need to read the docs. Always read the documentation all the way through. We all skim the docs to get the good parts but when you think you’ve done everything right and thing still don’t work, look over those docs again and read through them with a fine toothed comb. In this case the jQuery docs had a big yellow callout box disclaimer pointing out exactly what would happen if there were an error fetching a JSON document using $.getJSON(). Had the students just read the docs they’d have seen it and known immediately to check their JSON file.

Programming 101: Read the docs. Search the web. And when all else fails, ask for help either online or from someone you trust like your friendly, knowledgeable programming instructor.

Oh, and if you didn’t get the other takeaway it’s this: jQuery’s getJSON() callback will fail silently if you have malformed JSON. Check your JSON before calling any static JSON file.

Web development, jQuery

« Classes and Objects in JavaScript MySQL Cheat Sheet »