George’s Five Rules for Debugging
With all the automation available, sometimes we need to step back and review the basics.
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.
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.
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
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
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