The Console Frogger: JavaScript Debugging 101

The Console Frogger

Bugs don’t appear out of nowhere. We make each and every one of them. But they can be pretty nerve-wracking when they appear. Having a systematic approach for what to do when you see one will help you fix them faster and more effectively, and will help you learn more about your code.

What we’re going to do now is talk about some things that we can try for any and every sort of bug in our code, and then break down different kinds of bugs we might see, and the more unique approaches for dealing with each of them.

To-Do’s For All Sorts of Bugs

1. Remain Calm. We’re going to get through this.
2. Get help! Aren’t you happy when someone else asks you for help with their coding problems? Someone else will be just as happy to unpick yours. And it doesn’t have to be someone who knows more than you do, either. Just a pair of fresh eyes can go a long way to spotting mistakes.
3. Take a break! When in doubt, freshen your own damn eyes. If you can’t take an actual break, go work on something other project, or some other part of your application.
4. Google the error you’re getting. Google the error message. List the language you’re writing in. List the tools that you’re using to write it. In the results, look for people who have generated that error in the same context, or in similar ones. Especially when you’re just starting out, it’s reasonable to assume that someone, somewhere has fucked up this particular fuck up before. Learn from them.
5. If you’re having trouble pinpointing either where the error is, or what mistake is causing it, try this: comment out a wide swath of your code, until you disappear the error. Piece by piece, comment the code back in, until you’ve broken it again — hopefully you can isolate exactly what’s causing you’re problem. If you really can’t spot it, trying writing out the code fresh, sometimes you’ll overwrite a small error that your eyes just couldn’t spot from looking at the code for too long. Copy-editing is hard, and it’s a whole different skill!
6. Check the docs. Check them again. Find someone explaining the docs.
7. Don’t fear the error message! It’s here to help!

An Incomplete Checklist for Avoiding Bugs In The First Place

1. Test your code as you write it. Write a route, see if you can hit it and get the expected response. Write a react component, see if it renders the way you want it to.
2. In fact, consider writing tests for your code (better yet, write them before you write the code!) — this way, if you get your code in one part of the application working, and then something you write elsewhere breaks it later, you can always just run your tests to make sure your specs are passing (rather than hand testing every feature over and over again).
3. Practice good Git hygiene! Commit early and commit often. Commit with fantastic, descriptive commit messages too.
4. Related: work out tricky features on their own branches. That way, you can always revert to your last-working-version if you break everything and destroy the universe.
5. Get in the habit of writing beautifully formatted code. (5a: install a linter). If you’re consistent in your spacing, indenting and semi-colon habits, you’re a) more likely to be able to spot errors and b) less likely to make them in the first place.

Loud Errors

This is the first broad category of error. This is when our code literally breaks — stops running in the first the first place, and gives us some sort of error message. This might sound bad, but don’t be fooled. These are the good times. The happy times. You will miss them when they are gone.

To-Do’s for All Loud Errors:

1. Read. The. Error. Message. R E A D I T.
2. Read the stack trace to figure out where the error is being thrown. You should be able to find the file name and the exact line number where your code is breaking.
3. If the error is being thrown by your node modules, keep going down the stack trace to hopefully find the bit that is being thrown by your code (express probably does not have a bug in it). 3a) if you go through the WHOLE thing and none of it is your code, check what modules are throwing the error, and start checking the places where you use them.

Types Of Error Messages (In JavaScript)

There are six types of JS error message. The first three, you’ll see pretty often, the rest you probably won’t see as much.

1. Syntax Error: Your code won’t parse. Translation: You have a typo.
   Solutions:
   i) go check that line number. (see also: your linter)
   ii) know that a syntax error will be generated by the line where the code itself breaks — often the actual typo might be in the lines above (or below, if you have a brackets problem)
2. TypeError: your code expects a variable to be one *kind* of thing, but it is in fact another. This is one that you’ll see a lot, because it can be caused by lots of different kinds of screw ups. error messages like “cannot read {property} of undefined” or “{such and such} is not a function” are generally type errors. This is a very non-exhuastive list of solutions, to give you an idea of where to start looking.
   i ) console.log(typeof offendingVariable) to see if it’s what you expect/need.
   ii) check the formatting of your function — is it being called *on* what it should be called on, is it structured correctly?
   iii) is your data moving where it should? (console.log your function arguments and maybe their types?)
   iv) if this error is being thrown by your use of a library, check the docs to see if you’re using it right.
   ivA) try to find examples of other people using that tool!
3. ReferenceError: You’re referencing a variable that does not exist. Solution: look for where you think you’ve defined it, or where you should have defined it. you will likely find that you have either a) made a typo, b) imported/exported incorrectly c) not actually declared it at all or d) made a scoping error (eg, using “let” inside an “if” block, and then referencing that variable outside the code block). Solution: look for where you think you’ve defined it, or where you should have defined it. you will likely find that you have either a) made a typo, b) imported/exported incorrectly c) not actually declared it at all or d) made a scoping error (eg, using “let” inside an “if” block, and then referencing that variable outside the code block).
4. RangeError: Raised when a numeric variable exceeds its allowed range (solution: don’t do complicated math in javascript. or at least, use a special math-y library for it. alternately: fix your callstack.)
5. EvalError: you’re using eval() wrong. but if you get this error, you know you’re using eval() wrong, because you’ve decided to use eval(). Don’t do that.
6. URIError: Raised when the encodeURI() or decodeURI() functions are used in an incorrect manner. Lots of cool libraries exist just so that you never have to make this error. Like Express. Or Koa. Or Hapi. Consider using one.

Silent Errors

This is for the rest of the time. Our code is running, it’s not breaking, but it is not giving us the output we expect or want. These are the sad times. The dark times. The lonely times.

To-Do’s For Silent Errors

1. Diagram out our desired data flow with a pen and paper. Start tracing it out with console.logs, and try to find the point where we go from having the right outputs to the wrong ones.
2. Check to make sure that we’re actually executing the code we’re expecting to: console.log just to make sure we’re getting through to the blocks we should be.
3. Talk through what should be happening, with a teammate or fresh pair of eyes. see if anyone can spot a logic-error.
4. Check the docs for the technologies you’re using — do built in functions return the data you expect, in the format you expect?
5. Brainstorm alternate ways to solve your problem. What is the goal of your code? If the approach you’re debugging just isn’t unfucking itself, could there be other ways of achieving the same goal?

These are just some very basic kinds of errors, and ways of looking at solving them. Especially as you start to use more JS tools and libraries, you’ll encounter all kinds of new and exciting bugs, but these same principles will at least give you a place to start.

If you’d like the meat of this in super-short, light markdown, check out my github repo here: https://github.com/LeighSteiner/deBuggerChecklist. If you think I’ve made any terrible mistakes that you want to yell at me about, or if you want to add some more tools and trips, feel free to send me a pull request!