The Wrong Picture (Ep. 6)
How I messed up • When an analogy doesn't work
I took the kids to the museum the other day. There was an exhibition called "Python Programming Through The Centuries", showing the tools and methods used to program in Python from prehistoric times until the modern day.
In one of the rooms, there was a display cabinet with items the Sumerians used (c. 4000 BC) as debugging tools when coding in Python—the precursors of the debugging rubber duck.
Next to this display there was a vending machine stocked with crisps and drinks. This was odd. Thinking about it, lots of things were a bit odd about this museum.
We could look into the display cabinet. But with the vending machine, we could insert some money, tap a few keys, and get one of the items out.
Let's explore the Python special method
__getitem__(), which will help us understand the difference between the display unit with the Sumerian debugging tools and the vending machine with the snacks.
This was the introduction I wrote for a Python article I published a while ago. I know some of you who read Breaking the Rules also read The Python Coding Stack. If you can't remember reading this introduction, don't blame your memory. I never published these paragraphs. Until today.
I used a different story to frame the article about __getitem__() because the more I thought about this analogy of the museum cabinet and the vending machine, the more it fell apart.
Not all analogies are good analogies • Here's the story of how this analogy went wrong. There are some analogies I've worked on for years. But this wasn't one of them.
I decided to write an article about a Python command called __getitem__(). If you're not familiar with Python programming, all you need to know is that it allows you to fetch an item from something with many items within in. For example, let's assume you have a shopping list called items_to_buy in a program. You can use square brackets, such as items_to_buy[2], to fetch an item from the shopping list, but only if this weird-looking command, __getitem__(), exists.
So I brainstormed, came up with a few ideas, and settled on this analogy. I wanted a slightly surreal scenario that shows two things that contain items. You could fetch items from one but not the other. The article would have gone on to deal with a "museum display" that doesn't have this __getitem__() command and a "vending machine" that does.
Great job, you're thinking. And I had started writing the code for this article, too.
But here's the problem.
Let's return to the shopping list example. If you run items_to_buy[2] in your program, you'll see what item is in that position, but the item will not be removed from the shopping list. So, you can see the item but not remove it from the shopping list. You'll need something else for that.
And that's where the analogy failed. I intended to show that the vending machine meets this requirement, but the display cabinet doesn't. But when you "fetch an item" from the vending machine, you remove it from the machine (unless it gets stuck!). This is not what happens with __getitem__(). And you can still "look" at an item in the display cabinet if you wish, which is what __getitem__() does, sort of. The real-life scenarios didn't match the programming requirements closely enough.
Going off-piste • I discussed the key ingredients of a good analogy in Episode 2: Whizzing Through Wormholes. The analogy needs to describe items or events that most people are familiar with, and there must be a good correspondence between the items in the analogy and the technical concepts they represent.
This analogy does OK with the first criterion but not with the second. The purpose of an analogy is to use an everyday item or event to clarify how the technical concept works. But the wrong analogy can lead the reader down the wrong path and misunderstand the concept. Having a wrong understanding of a concept is worse than not understanding it in the first place.
The fudge • Since this substack is about stories, let me finish the story about this article. I had invested time and energy in developing this analogy. But then I decided to ditch it for the reasons I outlined above. It's tough having to throw away an idea.
But I made another mistake. I tried to hang on to parts of the idea. The new story I used to frame this article about __getitem__() still had a vending machine. This time it was placed in a classical library in an old manor house. It was better, but still not perfect. I give myself a 5 out of 10—must try harder.
Afterword • I suppose all writers hope their writing improves over time. This doesn't mean the improvement is linear. Not every article will be a bit better than the previous one. Not necessarily.
I'm thinking about regularly re-reading my own articles with a six-month delay. I'll let you know what comes out of that exercise.
I can say confidently that, if I look at anything I wrote more than 2 months ago, I want to rewrite it today.