Sometimes bugfixing is a near-zen demonstration of your mad l33t skillz. You stare at the problem for a few seconds, nod sagely and deliver a short flurry of keystrokes. The bug is squashed and the crowd goes wild.


Other times you spend the afternoon hammering furiously at the keyboard, swearing, questioning browser vendors' heritage and considering a career change to "something with no computers".

Worst of all is when it turns out to be an extraneous space, missing quote, or you were editing the wrong freakin' file the entire time.

It does not matter how smart or experienced you are, everyone makes mistakes. Unless you can guarantee your zen master approach 100% of the time, it helps to habitually and consciously rule out the simple stuff first.

A simple checklist

  1. Are you editing the right thing?
  2. Are you testing the right thing?
  3. Are you recreating the conditions?
  4. Is it a basic syntax problem or typo?

Now the really hard bit

It's easy to ping through that checklist thinking yes yes yes yes... but here's the hard bit: really check. Do you just think all those things are right? Or do you know?

Knowing what you think

Bugfixing is largely about changing things you think into things you know. At the start, you think you've done things right but you know the damn thing's busted.

So you break down the situation into the pieces you know are involved; and you eliminate variables and potential sources of errors. At the end either the error's been eliminated, or you know for sure what's broken and you can get to work.

The trap is skipping the basics, only to end up swearing at a typo and feeling like an idiot.

It's smart to check the basics... what you want is proof the basics are not causing the problem. Don't think, know.

How to really check

Let's run through that checklist again, but expand it. To put this list into perspective, I have seen every item on this list waste someone's time.

Are you editing the right thing?

  • Is it the right file?
  • the right location?
  • the right branch/fork of the repo?
  • ...and you've updated your checkout?

Are you testing the right thing?

  • Is it the right URL? Check the name, protocol, queries...
  • Did you definitely deploy, did the deployment definitely work?
  • Are you definitely seeing your changes take effect?
    • Force-refresh the browser, flush the cache, etc...
    • Log a fresh message in something you know is executing
    • Add a visible CSS debug. Remember your bug could be selector weight, so use properties you're not setting already, eg. put an outline on the element, add .foo:after { content: "debug1"; }, or even set display:none to be totally sure a certain rule is applying.
    • If all else fails with CSS and JS, view source at the desired location.

Are you recreating the bug?

  • Is your test case definitely set up correctly?
  • Are you using the right browser, platform and device?
  • If it's IE, is it set to the right rendering mode?
  • Are you following the same exact steps as the person who reported the bug?
  • Are you logged in with different permissions to the reporter?

Is it a syntax error or typo?

  • Do the variables/classes/IDs match in all locations? If in doubt, copy and paste them - especially between files.
  • Are all quotes, brackets, semicolons, etc correct and balanced?
  • No typos in the language, functions etc? Don't just check the variables.

Did you rule out a simple error and get back to doing something more fun? Good!

Why does a simple checklist work?

Chances are you just need to break yourself out of code blindness. When you work on something for an extended period, you start seeing what you expect to see, not what really is there. You've stopped looking at bits of code you've filed away as "done". You're not actually reading the class and variable names any more. You're too close to it.

That's why fresh eyes help: coworkers often pick up basic mistakes in over-the-shoulder checks, just because they're reading it for the first time and processing it differently. Explaining an approach during pair programming can have a similar effect; as does rubber duck problem solving.

Still have a bug at the end of all that?

If you've checked all the basic stuff and still have a bug, well, now you're getting into deep debugging - a topic to itself.

The point is you aren't wasting your time writing increasingly-clever CSS in the wrong file, or trying to make your awesome JavaScript work when it's not being called in the first place.

Machines can do the work

The checklist seems long when it's written down, but most items take just seconds to check. You will know what you've been changing, you will know your dev environment's quirks, you will know what to check first.

Even so, your tools should be set up to do things for you automatically:

  • Show the git branch and status in your bash prompt
  • Colour code terminal windows: green for dev, orange for staging, red for production...
  • Add visible debugs on staging servers with http headers or user stylesheets
  • Use syntax highlighting with really obvious bracket matching
  • Run code checks like JSHint in your editor (before you commit)
  • Exclude target/export/production directories within your editor's project, so when you search for code you don't open the wrong copy
  • etc!

There are plenty more tricks, the idea is to make errors obvious as easily and early as possible. You don't need to spend endless hours setting up every possible thing, but if you've made the same mistake several times then it's worth automating preventative measures.

Last thoughts

You probably know the IT Crowd joke: have you tried turning it off and on again... are you sure that it's plugged in?

It's funny because it rings true. You should check for simple things, because they can derail anything that comes after them - and you'll be really annoyed if you missed them at the start.

If you habitually rule out the basics, you'll find it takes very little time to do but saves you a great deal of frustration. It's smart to check the simple stuff.