Debug like a detective

One of my favorite things about writing code is debugging. Yeah, I know what you’re thinking. Insanity! It’s much more fun to write buggy code than to unravel it! But problem-solving is fun. It’s why I became a developer in the first place. After a lot of menial labor type work I was bored and wanted to use my brain. Plus, I get to pretend I’m a detective!

As a software developer, only part of your day is always devoted to writing code. Often the lion’s share of your time is spent solving the bugs you’ve written (if you’re lucky) or those you didn’t (if you’re most of us) or reading through code others have written helping them avoid bugs.

You could look on this exercise as a dull task that must be executed and find no joy in it. But let me tell you, Gentle Reader, it’s still far more entertaining than scrubbing toilets, waiting tables, or making lattes for a living.

Debugging is kind of like a classic mystery storyline. A crime is discovered. Tension builds. The detective has a hunch but can’t quite put it all together. The prospect of losing one’s badge, personal relationship, or even life do not deter the detective one bit! She has a curiosity itch that must be scratched. A sleuth will find answers, no matter the cost. The resolution is its own reward.

While developing my debugging skills, I’ve discovered a few good tricks along the way. It’s important to develop a well-honed use of the tools of the trade before wandering into dangerous situations.

How I like to imagine myself sleuthing

probably closer to the truth…

1. First off try to describe the bug out loud. If you have a rubber ducky handy, tell him what is wrong and I promise he will listen without interrupting. Part of the way through you may already have a eureka moment. If not, feel free to talk to another human being. Talking to a duck or anyone, really, forces you to use a different part of your brain.
2. Take a short walk. Timing here is key. There is a temptation to give up when problems get hard, and this is by no means what I’m suggesting. Take 15 minutes, not several days. Often you are stuck in tunnel vision so a short break may give you fresh eyes.
3. Ask yourself what is different since it was last working? Usegit log to see the change history, then roll back to a commit where was working. You can compare files & use the diff to see what changed. Sometimes new code doesn’t introduce bugs, it just uncovers them! Beware the pointy finger of blame as it may point right back at you.
4. Where exactly is it broken? You can’t fix something until you know exactly where it’s broken. There are endless tools for this: breakpoints, printing out log statements, etc. Developer tools are the best, though. Choose your weapons well and get really comfortable with them. If you have confidence it will be easier to use them when everything seems broken.
5. Console.logs: no one should leave those in shipped code. Like, EVER. I’m looking at you, Pinterest.
6. If you are a front end dev then the majority of debugging is probably going to be related to state. React’s dev tools can allow you to dial in and verify state variables as things change on the screen. Ember and Angular have similar dev tools, and I’m guessing Vue does too. This instant feedback allows for a fast iteration process when it comes to finding exactly where, or more importantly when bugs are happening. Redux also has amazing dev tools that will help demystify what is happening.
7. Go to documentation for answers first. Only after looking at docs and finding nothing should you go to Stack Overflow. If you go there first, without fundamentally understanding things, you will do future you a disservice. You may encounter a lot of misleading and plain wrong advice that the official docs will not have.
8. Try the dumbest thing first, so you can test your assumptions. Hardcode variables, use fixture data, or any of the other things you would use for a unit test. Strip away all the layers that alter expected output from input. Eventually you will find the layer where things are not working as you expect.
9. Break a problem into it’s smallest components to understand how each part works. Check these code snippets into your Github repo so you can refer back to them. Not only are you solving the problem you have now but you’re developing a problem solving arsenal.
10. If all else fails, search for the exact error message in Google. It might be a known bug or quirk that isn’t even your code. Then feel free to shake your tiny fists at the heavens or in the general direction of whoever wrote that code.
11. If it was working locally but it doesn’t after you deploy, it’s probably an environment variable.
12. If it is working on your machine but not another one it may also be environment-related. With any project running on Node it’s good practice to wipe out the Node modules directory and clear your cache from time to time.
13. If you find that things mysteriously fail often on your machine, remember to update your OS frequently and avoid letting updates to your dev tools go for too long. Nothing is more frustrating than realizing you were just using a really old version of yarn. This is especially true if you do anything with ReactNative on a Mac as there are sneaky dependancies on xcode.

As a side note, it’s good practice to reformat your hard drive every few years or so. Upgrade to the latest OS & reinstall everything. You will find you may not even need an upgraded machine after a few years. This works like a charm and will keep your wallet happy! Plus, fewer old laptops for the trash heaps.

I hope this helps! Please feel free to share your favorite debugging tips with me in the comments!