Have you ever been called out on a code example because it just wouldn’t work in the real world? It’s happened to me a few times and gradually I’ve learned that, far from fixing the problem, the answer is often to make my code even dumber.
This is a problem that all those who use code examples have to consider to some extent. Here’s the great Martin Fowler, for instance, writing about a dependency injection example.
To help make all of this more concrete I’ll use a running example to talk about all of this. Like all of my examples it’s one of those super-simple examples; small enough to be unreal, but hopefully enough for you to visualize what’s going on without falling into the bog of a real example.
It’s tough to do, though, because no-one likes to write bad code deliberately, and certainly no-one likes to be seen to write bad code. There is a central problem here which falls foul of one of the core principles of good coding. In the real world, a component should do one thing and do it well. Side effects and other forms of double duty are seen as bad practice. If you use a component to achieve a particular purpose without realising that it magically sneaks in extra work, chances are something unexpected is going to happen (at best) or get broken (more likely).
Almost by definition, pedagogic code pulls double duty. It must perform its pretend task (representing an invoice, reading a configuration file, managing appointment objects, whatever). But its hidden real job is to teach something – to demonstrate a principle. The core lesson needs to shine out from the code to the reader. The last thing you need is to obscure your message with nonsense like error handling and general robustness, in fact, most of the features that make good code good.
This is the contradiction of example code. You want it to seem real. But not so real that it gets mistaken for.. er real code. Designers and UX people have a similar problem with wireframes. Make something seem too real and, before you know it, you’ll be taking flack for absences that are deliberate (or, in the case of wireframes, you’ll be defending the colours of your buttons when you’re really only demonstrating site structure).
So why not make it entirely unreal? Why bother with fake shops and colleges? Why not simplify components down to objects named Blah and Foo? Actually, for simple examples that probably makes sense – keep simple things simple in form. But it’s worth remembering that a tech article or chapter is also a story. We’re leading the readers on a journey and we want to engage their interest. We want them to see why the principles we are illustrating matter and that they can be applied to the real world problems.
So what’s the answer? For a start, it doesn’t hurt to emulate Martin Fowler (it never hurts to emulate Martin Fowler) and add a disclaimer either inline or in a callout note. You can also add comment blocks of the add error checking here variety. Mostly, though, it is a matter of keeping the code deliberately and obviously simple.
Imagine a pantomime cow – the kind played by two actors in a ridiculous suit. The cow plays a role in the show, it does stuff to move the story along and it makes you laugh. For the purposes of the performance, you will probably suspend your disbelief and accept that there’s a cow dancing up there. The fact that it doesn’t really look all that bovine is beside the point. It’s a contract you understand. Replace the pantomime cow with a bad CGI animation, on the other hand, and the show may go less well. The failure to be cow-like seems suddenly much worse, even though the animation looks more like the real thing than the guys in the suit ever did. The poor beast is stuck in the uncanny valley.
So, make like the guys in the suit. Keep the code simple – have it mime real actions, but don’t sweat the realism.
photo credit: trippy cow (panto style) via photopin (license)
