George’s Five Rules for Debugging

With all the automation available, sometimes we need to step back and review the basics.

George Alan Heimel
Nov 12, 2018 · 6 min read

Between modern IDE’s, automated linting, advanced cli’s and technology like Selenium, it is easy for developers to let the tools do the testing. It is also possible to have all the automated testing in the world tell you your code is perfect, yet we don’t end up with the results we expect. On those rare occasions, the developers’ fervent cry of “that’s impossible” rings out, and we need to get back to basics to ease the pain.

I have boiled my years of code writing and debugging down to a set of five seemingly simple rules. If they seem overly simplified… they ARE. They have been condensed because much more detail than this then people forget them or they glaze over and don't get through all the rules. These rules scratch the surface of more complex discussions, but this is meant to introduce those larger topics. I may expand upon some of them in the future.

Rule #1: There is ALWAYS a reason

Despite the statements like:

  • That’s impossible
  • It can’t be doing that
  • There is no reason for that code not to work

There is ALWAYS a reason that code either breaks, gives the wrong result or won’t even compile. ALWAYS. Even when the linter says it is all good. Sometimes we get so deep into the code and what we are currently looking at we lose sight of the bigger picture. Most web, app or software project these days are complicated things. The more ambitious the project, the more moving parts and details there are. There are just so many ways that can affect your code that we can get lost in the errors and not remember that.

Image for post
Image for post
PEBKAC

Take a step back. Take a deep breath. Then take another look. Don’t rely solely on the tools. Review your logic and step through it. Look at how the piece you are working on fits into the larger whole. There is a reason for a problem and many times it is a PEBKAC issue. Problem Exists Between Keyboard and Chair.

And for goodness sake when you are trying to fix something, please don’t change ten things and then wonder which one did not work. Sometimes debugging requires a little patience and a lot of small changes. Be methodical and precise like a scalpel, don’t be the shotgun.

Rule #2: RTFM & WTFV

Most developers are pretty smart people. Sometimes too smart for their own good. We all think “I don’t need the intro or basic tutorial. I can jump into the advanced stuff because I’ve used something similar before!”

Ok, sure. Most of us can get by with the ‘learn as we do’ method for most simple projects. The issue arises when you are several weeks into a larger, more complicated project and realize that you wrote everything based on a wrong assumption about that new framework, language, tool, etc.. You will now have to waste time and sleep to fix it. Take the basic step and:

Read the F***ing Manual or Watch the F***ing Video.

Image for post
Image for post
Photo by Christin Hume on Unsplash

Sometimes there is a small crucial detail in the basics of a new programming ‘thing’ you are using. Stop whining, put on your big person pants and just do it. Even if you fly through the basic information at least get through it. I have seen many projects get delayed because of having to refactor based on a developer’s lack of basic knowledge about the language or tool they are trying to use. In no way am I saying that the person was not, in fact, a damn fine developer. They just skipped to the end of the book and missed a few crucial sentences at the beginning.

Unfortunately, it seems that every couple of days there is a new framework, or language or major version of an existing tool that we need to understand so we can be effective. There is a lot to know and to keep up with. Oh well, good thing we are smart people huh?

Rule #3: Please refer back to rules 1 & 2

So we looked at the code and diagrammed our logic. We spend a couple of hours reviewing the documentation and tutorials. Now… zilch. No breakthrough, no solution. Unfortunately, that usually means you did not look in the right places. No one said this would be easy.

Rule #4: Blame the original author

Image for post
Image for post
Photo by Gem & Lauris RK on Unsplash

On occasion, well more often lately, there is something that changed in either a tool or a library you use. If you are a web developer this is especially true of javascript frameworks, libraries, and tools. The pace of updates has increased to a somewhat hectic level. Fortunately, there are a lot of people doing this work and using these tools. Google provides a gateway to other developers trials and tribulations. Sites like Experts Exchange and StackOpen, and the support forums for the specific tool provider are all great places to look for solutions or similar issues.

So now we have checked all the issue trackers and wiki’s and forums to see if anyone else is having the same problem. We still need to fix the issue. Gather the intel and refer back to Rule #1.

Rule #5: Get a shot of bourbon and start again

Image for post
Image for post
Photo by Adam Wilson on Unsplash

Sometimes we really can’t see the forest for the trees. Staring at screens of code for hours, looking for the one thing that is out of place can be mentally and physically exhausting. If you have been back through the rules the minimum of three times required and still do not have an answer, perhaps it is time to give your poor tired brain a break.

Sometimes just walking away from the problem and relaxing a little bit clears out the all the noise and lets your brain churn on the issue in the background. Especially after trying to debug a particularly difficult issue, the mix of frustration, anger, and exhaustion can cloud anyone’s reasoning skills.

Just not looking at the screen and talking through the issue with someone else may give you new insight. When it seems the answer will never come, especially if you are on a deadline (what are those?) the internal and external noise can be very distracting and prevent you from seeing an answer.

The definition of insanity is doing the same thing over and over again, but expecting different results. — Albert Einstein

Get some food. Have a shot of your favorite vice. Maybe even get a good night’s sleep. I keep a nice collection of small batch Bourbons that need some attention every once in a while. I am not suggesting picking up a life altering, self destructive habit; just take a break. I have come up with solutions to problems in those twilight moments just before falling asleep. Give your head time to clear out the junk from the previous attempts and look at the problem from a fresh perspective.

Then… you guessed it. Back to Rule #1

square360

We are digital natives stuffed inside design emissaries.

George Alan Heimel

Written by

CTO Square360: technology artist, database dreamer, code monkey, knowledge collector and pie aficionado

square360

square360

We are digital natives stuffed inside design emissaries. Our expertise is your advantage.

George Alan Heimel

Written by

CTO Square360: technology artist, database dreamer, code monkey, knowledge collector and pie aficionado

square360

square360

We are digital natives stuffed inside design emissaries. Our expertise is your advantage.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store