The universe's plot

I used to banter with a friend whenever they had a code issue and were on the verge of giving up. Feeling worn out and discouraged, they would describe the problem while implying that they had done everything right but the code was still misbehaving. After listening to their plight, one of the things I would jokingly say is,

Oh, that is unfortunate. Let's file an issue with the Node.js team since it must be from their end 😁.

We would laugh it off and soon enough, they would end up finding out what was missing from their code. Spoiler. It was not the runtime (yet anyway).

Times like these arise for many developers. Times when we are so sure that everything about our code should work perfectly. In fact, during those times, we are almost ready to go out on a limb for our code. We insist we have done everything right and that it is perhaps the programming language or framework or the universe at large conspiring to hold us back from greatness. (It sometimes is the language or framework indeed. Don't rule it out simply because I implied so 😊.)

There are many helpful tools for stepping through code to help know what might be causing a malfunction. However, in this debugging series, our focus will be on behavioural approaches that could help in finding the cause of bugs more efficiently. This in turn will help reduce the usual frustration that comes with debugging.

This article addresses how to conveniently deal with hunches and assumptions when something isn't working right with our code logic.

How it goes

Sometimes, when our code is not working, we naturally have certain spots in the code we are already not confident about. As a result, they are unofficially ranked highest on the suspects' list and are the starting points.

In a similar vein, other times, it is actually because we are most certain about specific parts of the code such that we rule them out altogether and probe more into any other part whether related or not.

Having a hunch or assumption about the cause of a malfunction is inevitable. They just show up. This could be due to prior experience or sometimes due to a much less logical reason. However, if it turns out well, it cuts the whole bug fanfare short.

Is this a good or bad thing? Let's see.

Two sides of the coin

When it comes to using a hunch or assumption in debugging, a case can be made that, exploring the wrong place for the cause of a bug is technically not a waste of time. This is because finding the cause of the bug is as essential as finding what is not the cause. It helps to clear stuff off the suspect list to help zero in on the cause. However, there are times we are so convinced there is possibly no other cause even when a hunch or assumption is yielding nothing. Debugging based on a random hunch with no basis makes one spend time and energy chasing shadows.

Debugging this way leads to exhaustion and loss of desire to continue. This is not to say finding the cause of a bug should necessarily be a quick affair. The main aim here is to increase the chances that we are focusing our time and energy on the right things.

When it comes to what we think might be causing a bug, it requires more substance. Our suspicions need to be supported by initial facts and confirmation from the source code or documentation.

Exhibit A: A hunch borne out of earlier curiosity

A couple of years ago, I was part of a team in charge of designing widgets for websites. This included integrating with sites on eCommerce platforms like Shopify, Wix and Bigcommerce. We had successfully launched and our widgets were functioning properly across all platforms. All except one Shopify website. The website had 'decided' not to show the widgets at all. What made it even more challenging was that every other Shopify site was playing nice so there was no other site to draw a pattern from.

Stuck with the issue for a few days, I remembered something I had been curious about some weeks before and had a strange feeling it might be playing a role. It was about how code bundled by Webpack had a global variable, webpackJsonP, used for loading other scripts (chunks) of the code when needed. These chunks are the result of a concept called code-splitting which splits code into smaller different parts based on the code structure. It helps to load only the needed CSS and/or Javascript on a site instead of loading an enormous amount of code that might not be required at the time.

Not too much information, I hope 😅. Let's proceed then.

At the time, I remember being curious about what would happen to the webpackJsonP variable if two separate app codes bundled by Webpack were on the same website. I had no idea that I would learn the answer to that the hard way a few weeks later.

Following up on the hunch, I found out another third-party app installed on the site had also Webpack for bundling their code. Due to this, the app had first rights to the global webpackJsonP variable because it had been installed before ours. As a result, it was loading the scripts of the other app and not ours. Our app had no chance.

The fix was to configure Webpack to customize the name of the global variable^[1] when bundling our app code and voilà!

Working with hunches the right way

Given that they can be unintentional, there is no correct method to have an assumption or hunch in and of itself. However, acting on an informed one can go a long way.

An essential initial approach to validating hunches and assumptions is to try to reproduce the bug with the theory and information at hand. In my case, to confirm my initial hunch that another app was playing a role in the widget malfunction, this is what I tried: I created a sample Shopify site and installed our app. Widgets appeared and worked flawlessly. Next, I uninstalled our app, installed the other app in question, and then reinstalled our app. Result? The network requests would not even show any javascript being loaded for our app. Hunch confirmed. Note that this did not mean a fix had been figured out but was a giant step in the right direction. This ties into the next article in this series we will be talking about.

Additionally, one should infer from the source code itself, NOT a memory of the code, even if one is the sole programmer on the project in question. Inferences can also be made from past experiences or something that caught one's attention while testing something unrelated.

In conclusion, getting a logical and factual basis for any hunch or assumption about what could be causing a code malfunction helps to meet fewer dead ends and reduces frustration.

Thanks for reading! Any thoughts and further experience on this are highly welcome.

1. This is no longer an issue in Webpack 5 onwards.