Syntax Error #9: Distilling the minimum example

A lot of bugs arise from the complexity in software and they like to hide in that complexity. The ability to distill your current problematic code into something that reproduces the bug while clearing all the extra off, is vital to making sense of these issues.

Happy November everyone, old friends and new subscribers alike!

The year is coming to its end and for us developers, that means Advent of Code is right around the corner. If you're not familiar with it, it's an annual Christmas programming puzzle calendar. Starting December 1st, each day until the 25th, you get a puzzle with a nice bit of Christmas lore and you can solve the puzzles with any technology you like. The solutions are alphanumeric results based on your unique input.

I've been enjoying it to learn new things and experiment with new languages and technologies. For the past couple of years, I've focused on solving the problems using Python and Jupyter Notebooks while writing educational content around them.

Greetings from PyCon Sweden

Juhis on stage standing behind a speaker podium. On the podium, there's a laptop, an iPad and a cute avocado plushie. Juhis is wearing a grey hoodie and black jeans. On the background, a projector screen with a slide that has a yellow rubber duck illustration and title "Debugging Python - what to do when computer says no".

Last week, I had the privilege to visit Stockholm and PyCon Sweden to talk about my favorite topic: debugging. I hope to share the recording of the talk in next month's newsletter as the videos are not yet available today. In this talk, I talked about many of the topics I've touched on this newsletter as well: the debugging mindset, printing being the best debugging tool, rubber duck debugging and making sure you are running the code you're changing.

In addition to the talk, I had plenty of lovely discussions with other pythonistas and learned about a ton of new tools and approaches people have for debugging. That's what I really love about these conferences: meeting each other, learning new things and having a great time.

I also gave out a bunch of Syntax Error stickers. If you ever see me in an event, come say hi and ask for one, I try to keep them with me at all times!

The importance of minimum examples

Software is complex. This complexity leads to bugs that are difficult to debug because there's so many interconnected things happening. What ever your method of debugging is, learning how to remove all the extra cruft and crafting an example that still replicates the bug but nothing else is a highly valuable skill.

First, it makes it easier for others to help you. I have previously written about how to ask help for technical problems and if you're asking someone to help you with a bug, making it easy for them should be a priority. The less irrelevant code there is, the easier it is for someone else to figure out what's happening, tweak the code and run it and reach a solution.

Another part of making it easy for others to help you is being clear about the intended inputs, expected outputs and any incorrect behaviour you encounter. "Any ideas why X is failing" is not a very helpful or useful query to anyone so take the extra minute or two to figure out the details.

This is helpful regardless of who you ask for help: whether it's your colleague, an online developer community, Q&A site like Stack Overflow or your rubber ducks.

Second, it brings clarity to your thinking process. Similarly to how talking to your ducks forces you to make your thoughts more concrete and avoid skipping any details, working with your code to make it as simple as possible often unlocks the issue at hand before you have time to ask for help.

Many bugs arise from complexity of software and that's a great place for bugs to hide in. As we unwrap that complexity, it's easier to spot the issues.

I have also noticed over the years of writing that when I switch from coding to writing, I look at the code in a different way. I use it as an extra layer of refactoring but it also applies to debugging. When I explain my code to someone else in writing, I notice much easier those things that stand out as weird or inconsistent.

Story time

If you have debugging stories or examples you want to share to the Syntax Error community, please reach out via and we might share your story!

This month I have two small print related funny stories.

The first one comes from the Unix & Linux StackExchange:

We've noticed that some of our automatic tests fail when they run at 00:30 but work fine the rest of the day. They fail with the message gimme gimme gimme in stderr, which wasn't expected. Why are we getting this output?

Tests that fail based on a specific moment in time can be really tough to debug. The story behind this one though, is just too good:

Pretty much the whole story is in the commit. The maintainer of man is a good friend of mine, and one day six years ago I jokingly said to him that if you invoke man after midnight it should print "gimme gimme gimme", because of the Abba song called "Gimme gimme gimme a man after midnight"

Well, he did actually put it in. A few people were amused to discover it, and we mostly forgot about it until today.

While this first story revolved around unexpected print at a given time, the second story is about not being able to print at a given time. It comes from Andreas Zwinkau's blog post OpenOffice does not print on Tuesdays:

The problem was that printing for some people failed occasionally. Later someone noted that his Wife had been complaining that she couldn't print on Tuesdays!
[- -]
The problem seemed to be tracked down to a program called 'file'.
[- -]
An error in the pattern for an Erlang JAM file meant that 'Tue' in the PostScript file was being recognised as an Erlang JAM file and so, presumably, it was not being sent to the printer.

Remember how I mentioned that software is complex? It's even more complex when we take into account the interoperability of not only past and current other software but all the software to be written after the original one.

Syntax Error is created with love by Juhis. If you liked it, why not share it with a friend? Or if you have any feedback or just want to say hi, hit reply. I'm always happy to hear from my readers and learn about what you do and how you debug your issues.

Subscribe to Syntax Error

Sign up now to get access to the library of members-only issues.
Jamie Larson