When I write about programming, I spend a lot of time trying to come up with good examples. I haven’t seen a lot written about how to make examples, so here’s a little bit about my approach to writing examples!

The basic idea here is to start with real code that you wrote and then remove irrelevant details to make it into a self-contained example instead of coming up with examples out of thin air.

I’ll talk about two kinds of examples: realistic examples and suprising examples.

good examples are realistic

To see why examples should be realistic, let’s first talk about an unrealistic example! Let’s say we’re trying to explain Python lambdas (which is just the first concept I thought of). You could give this example, of using map and a lambda to double a set of numbers.

numbers = [1, 2, 3, 4]
squares = map(lambda x: x * x, numbers)

I think this example is unrealistic for a couple of reasons:

• squaring a set of numbers isn’t something you’re super likely to do in a real program unless it’s for Project Euler or something (there are LOTS of operations on lists that are a lot more likely)
• This usage of map is not idiomatic Python, even if you were doing this I would write [x*x for x in numbers] instead

A more realistic example of Python lambdas is using them with sort, like this;

children = [{"name": "ashwin", "age": 12}, {"name": "radhika", "age": 3}]
sorted_children = sorted(children, key=lambda x: x['age'])

But this example is still pretty contrived (why exactly do we need to sort these children by age?). So how do we actually make realistic examples?

how to make your examples realistic: look at actual code you wrote

I think the easiest way to make realistic examples is, instead of pulling an example out of thin air (like I did with that children example), instead just start by looking at real code!

For example, if I grep a bunch of Python code I wrote for sort.+key, I find LOTS of real examples of me sorting a list by some criterion, like:

• tasks.sort(key=lambda task: task['completed_time'])
• emails = reversed(sorted(emails, key=lambda x:x['receivedAt']))
• sorted_keysizes = sorted(scores.keys(), key=scores.get)
• shows = sorted(dates[date], key=lambda x: x['time']['performanceTime'])

It’s pretty easy to see a pattern here – a lot of these are sorting by time! So now we can make a simple realistic example of sorting some objects (emails, events, etc) by time, like sorting some calendar events by their unix timestamp:

events = [
    { 'date': 1625837042, 'name': 'birthday party'},
    { 'date': 1620581136, 'name': 'dinner with Yifei'},
    { 'date': 1589045136, 'name': 'dentist appointment'},
]
sorted_events = sorted(events, key=lambda x: x['date'])

I think this is more realistic than the “sort children by age” example, and it’s just as simple!

realistic examples help “sell” the concept you’re trying to explain

When I’m trying to explain an idea (like Python lambdas), I’m usually also trying to convince the reader that it’s worth learning! Python lambdas are super useful! And to convince someone that lambdas are useful, it really helps to show someone how lambdas could help them do a task that they could actually imagine themselves doing, and ideally a task that they’ve done before.

distilling down examples from real code can take a long time

The example I just gave of explaining how to use sort with lambda is pretty simple and it didn’t take me a long time to come up with, but turning real code into a standalone example can take a really long time!

For example, I was thinking of including an example of some weird CSS behaviour in this post to illustrate how it’s fun to create examples with weird or surprising behaviour. I spent 2 hours taking a real problem I had this week, making sure I understood what was actually happening with the CSS, and making it into a minimal example.

In the end it “just” took 5 lines of HTML and a tiny bit of CSS to demonstrate the problem and it doesn’t really look like it took hours to write. But originally it was hundreds of lines of JS/CSS/JavaScript, and it takes time to untangle all that and come up with something small that gets at the heart of the issue!

But I think it’s worth it to take the time to make examples really clear and minimal – if hundreds of people are reading your example, you’re saving them all so much time!

that’s all for now!

I think there’s a lot more to say about examples – for instance I think there are a few different types of useful examples, like:

• examples that are surprising to the reader, which are more about changing someone’s mental model than providing code to use directly
• examples that are easy to copy and paste to use as a starting point

but maybe I’ll write about that another day. :)