2004 · 2005 · 2006 · 2007 · 2008 · 2009
2010 · 2011 · 2012 · 2013 · 2014 · 2015 · 2016 · 2017 · 2018 · 2019
2020 · 2021 · 2022

Software Design by Example Personas

These personas describe who Software Design by Example in Python is for:

  • Aïsha has a master’s degree in genomics and does very complicated science things in a wet lab. She has taught herself enough Python to do some sophisticated data analysis, but is constantly frustrated by what she doesn’t know about how software actually works. This material will take away some of the mystery.

  • Rupinder is studying computer science at college. He uses Git and style checkers in his assignments and wants to know how they work. This material will answer his questions and show him new ways to think about software design.

  • Yim teaches two college courses on web programming. They are frustrated that so many books talk about algorithms but not about design and use examples that their students can’t relate to. This material will give them material they can use in class and starting points for course projects.

Like these three personas, readers should be able to:

  • Write Python programs using dictionaries, exceptions, and classes. (We assume that if you can use these, you can also use lists, loops, conditionals, and functions.)

  • Create static web pages using HTML and CSS.

  • Use Git to save and share files. (It’s OK not to know the more obscure commands.)

  • Process a tree’s nodes recursively. (Trees and recursion are the most complicated things we don’t explain.)

You can read this book on its own or use it as a classroom resource. If you need projects for a software design course, adding a tool to those covered here would be fun as well as educational: please email me if you’d like to chat.

Journal of Comprehensible Explanations

I really, really want the ACM to start a “Journal of Comprehensible Explanations” in which people can publish peer-reviewed summaries of research findings (recent or otherwise) that are accessible to practitioners. JCE would specifically not allow reporting of novel discoveries; instead, articles present novel, peer-reviewed explanations.

Still Trying

Years ago, after I screwed up something important, I defended myself by saying, “I’m doing the best I can.” My brother replied, “Then try to do the best of someone better.” When I said, “Ouch,” he said, “Because if you try and keep trying maybe you’ll become someone better.”

So happy birthday, Jeff - I’m still trying.

Debuggable Explanations

Jon Udell has written a short post about his experience working through the Python version of Software Design by Example. He doesn’t jus want to read prose and code: he wants to be able to run the code in a debugger so he can step through and build a mental model of how it works. Downloading the samples figuring out how to run them on their own without command-line arguments, and arranging things for side-by-side viewing is doable, but as he says, “…the activation threshold is high enough to thwart my best intention of repeating the steps for every chapter.”

Tools like the Jupyter Notebook aren’t much help here: for example, they don’t provide a way to have a cell containing just one method of a larger class or just a few lines from a longer function (which I frequently want to do for pedagogical reasons). I did think about bundling a VSCode launch.json file with each chapter, but that wouldn’t do anything to put the code side-by-side with the explanation.

What’s funny/not-funny is that these aren’t niche needs. While JavaDoc-style comments or Python’s specially-formatted docstrings are OK (but not great) for API documentation, they’re a clumsy way to write long-form tutorials. I’ve been stumbling over this problem for over thirty years, and today’s solutions are only marginally better than what was available in 1989. If you have one—one that will make authoring easier while simultaneously allowing people like Jon to experience the lesson in the IDE of their choice—please let me know.

Support On Spec

Please support your local (or not-so-local) speculative fiction magazine:

On Spec banner

The Notebook Not Taken

I had the pleasure of seeing Alison Hill talk about computational notebooks last week. Jupyter, Quarto, Wolfram Notebooks, and the like are now many scientists’ preferred way to think in code. Having used several, I can’t help but wonder if there’s a universe out there in which we took a different path. Instead of starting with Markdown and slowly edging toward a full-featured editor, did someone on Earth-978 write a plugin for LibreOffice to run code and insert its output into the document? It’s technically feasible: there’s no reason something like the Jupyer protocol couldn’t have been invented with a WYSIWYG editor as the first front end instead of a browser.

Earth-977’s history took yet another path. There, Microsoft included what they called a “computational bridge” in Office 2007. It was designed to help people create automated reports, but scientists almost immediately adopted it as well: most of them were already using Word and Excel, and found that learning a bit of VB.NET to push around their dataframes was a lot easier than shifting to an entirely new suite of tools. By the time Google Docs appeared, active code blocks were as normal (and as expected) as drawings and tables. A few holdouts continued to use Python, R, and plaintext editors, but once a consortium sponsored by Microsoft, Google, and Apple implemented diff and merge for office documents, the battle was effectively over.

I suspect our universe unfolded differently for two reasons:

  1. Most computational scientists don’t know Java or .NET.

  2. Most programmers look down on WYSIWYG editors. As a result, auxiliary tools from grep to Git can’t handle things that aren’t backward-compatible with punchcards.

I believe the LibreOffice path is still viable in our universe. The unseen 99% of scientists (data or otherwise) don’t yet use computational notebooks of any kind. With the distinction between desktop and cloud growing ever blurrier, and with so many of the pieces needed for this approach already available, I think a startup could make a compelling case that accountants, marketing executives, and others would prefer something evolutionary over a browser-based dashboarding tool or something as alien as today’s notebooks.

Note: this post was inspired in part by my move from Twitter to Mastodon. The differences between the two have got me thinking about how chancy and evitable our technologies are, and about how many alternatives we have yet to explore.


Is there a MastodonConf yet? It would be near the top of my must-do list: the combination of tech talks about scaling federated services with process talks on encouraging or enforcing social rules for distributed content moderation and social scientists analyzing how people are adapting legacy (Twitter-era) practices to a similar-but-different ecosystem would be fascinating.

A Combinatoric Geometry Problem

Suppose you have a grid that’s W squares wide and H squares tall. How many different ways can you cover it with rectangular tiles? It’s easy enough to work out the answer for specific cases:

Grid Size Number of Tilings
1x1 1
1x2 2
2x2 8

but I can’t figure out the formula for the general case—a simple recursive formula double-counts configurations like the four size-one squares in the diagram below.


Later: several people have suggested divide-and-conquer strategies, but so far I haven’t seen one that would generate this case, where there isn’t a seam spanning either the entire height or width:

Another Tiling

*Later still: my brother asked me the question 20 years ago when he was starting a furniture-making company. Yetserday, Julian Berman got an answer from Bhavik Mehta at Cambridge: it turns out an undergrad in Louisiana named Joshua Smith, who was working with Helena Verrill, solved this in 2005 or 2006. Their work is online at https://oeis.org/A116694 and https://oeis.org/A116694/a116694.pdf, so, um, yay Internet, and thank you Helena, Joshua, Bhavik, and Julian.

Getting Closer

I don’t have hard copies yet, but we’re getting closer:

Cover of 'Software Design by Example'

Listening Means Changing Your Mind

The last two and a half years have been the most inclusive in tech conference history. Thanks (or “thanks”) to COVID-19, thousands of people were finally able to take part on an equal footing despite visa restrictions, not being able to afford to travel to an affluent country, needing to stay at home to look after loved ones, accessibility challenges, and a host of other barriers that had prevented them from doing so before. Yes, the experience wasn’t as rewarding for people who had historically been able to hop on a plane in order to take part in social events and hallway conversations, but that’s kind of the point: as a friend of mine once said, if two weeks on crutches with a broken ankle doesn’t teach you a little compassion, nothing will.

I’ve therefore been watching with dismay as conferences go back to supporting only on-site/in-person attendance. More than that: I’m angry that people who pay lip service to inclusivity are throwing away the (admittedly uneven) progress we’ve made during COVID-19 toward making it possible for everyone to take part in tech events because they miss playing boardgames with their friends. I decided in the spring that I would no longer attend events that didn’t support remote participation, then decided over the summer that maybe we could actually do something about this. If enough people were to make the same pledge, publicly, maybe that would shame conference organizers into doing the right thing.

So I sent the email below out to two dozen people in early September, and that’s when things got interesting:

I hope you don’t mind mail out of the blue, but we’d like to put some pressure on conference organizers to get them to offer remote participation even after COVID-19 ends in order to make their conferences accessible and inclusive. To do this, we’re organizing an online petition; we are still trying to decide what platform to use, but if you can spare a few minutes, we’d be very grateful if you could give us feedback on the wording below. We are planning to translate it into several other languages before we launch, and want to make sure it’s asking for the right things before we do so.

Thanks very much - I hope you and yours are safe and well.

  • Greg Wilson

We, the undersigned, believe that communities are only truly inclusive if everyone is able to participate. Now that video conferencing is widely available, we believe that no one should be shut out or left behind because they cannot afford to travel, are unable to obtain a visa, have health concerns, or need to look after family members. Accordingly, we pledge that we will not take part in any conference that does not provide an option for remote attendance unless required to do so as a condition of employment.

About a third of the people I emailed came back with, “Looks good!” Another third came back with detailed comments about the wording of the pledge, and the other third responded by saying, “This is a bad idea.” A handful felt that this pledge would put people in a no-win situation: for example, it’s basically career suicide for junior academics to not go to networking events (which is all conferences really are), so this pledge would force them to choose between solidarity with their friends and getting ahead with their own lives. It’s easy to say that if you’re not willing to make sacrifices for your ideals then they don’t really have any, but it’s also unfair.

Other people felt that focusing on one aspect of inclusivity—remote participation via video conferencing—was yet another example of someone treating a social problem as a technical one. What about other (more important) forms of inclusion? If people are going to pledge to do something, shouldn’t we encourage them to focus on the most important things?

My first reaction to these responses was to defend my idea: this is topical, let’s win one fight at time, etc. And if just one person had pushed back I might have done that, but a third? If you never change your mind based on feedback then you’re either much, much smarter than the people you’re listening to or you’re not actually listening, and I know I’m not the former.

All of which leaves me feeling a little deflated. I think collective action over remote inclusion could improve a lot of people’s lives in a small but significant way, but I have to accept that this pledge may not be the right way to do it. If you know a better one, please get in touch.