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_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
In the end we tracked down the issue to two problems:
getJSONmethod fails silently
- Their JSON had comments was therefore invalid
- 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.