Writing Idiomatic Python (2013)

Preface

There’s a famous old quote about writing maintainable software:

Always code as if the guy who ends up maintaining your code

will be a violent psychopath who knows where you live.

--John Woods comp.lang.c++

While I’m not usually one for aphorisms, this one strikes a chord with me. Maybe it’s because I’ve spent my professional career writing software at huge companies, but I have yet to inherit code that didn’t eventually cause me to curse the original author at some point. Everyone (besides you, of course, dear reader) struggles to write code that’s easy to maintain. When Python became popular, many thought that, because of its terseness, it would naturally lead to more maintainable software.

Alas, maintainability is not an emergent property of using an expressive language. Badly written Python code is just as unmaintainable as badly written C++, Perl, Java and all the rest of the languages known for their, ahem, readability. Terse code is not a free lunch.

So what do we do? Resign ourselves to maintaining code we can’t understand? Rant on Twitter and The Daily WTF about the awful code we have to work on? What must we do to stop the pain?

Write. Idiomatic. Code.

It’s that simple. Idioms in a programming language are a sort of lingua franca to let future readers know exactly what we’re trying to accomplish. We may document our code extensively, write exhaustive unit tests, and hold code reviews three times a day, but the fact remains: when someone else needs to make changes, the code is king. If that someone is you, all the documentation in the world won’t help you understand unreadable code. After all, how can you even be sure the code is doing what the documentation says?

We’re usually reading someone else’s code because there’s a problem. But idiomatic code helps here, too. Even if it’s wrong, when code is written idiomatically, it’s far easier to spot bugs. Idiomatic code reduces the cognitive load on the reader. After learning a language’s idioms, you’ll spend less time wondering “Wait, why are they using a named tuple there” and more time understanding what the code actually does.

After you learn and internalize a language’s idioms, reading the code of a like-minded developer feels like speed reading. You’re no longer stopping at every line, trying to figure out what it does while struggling to keep in mind what came before. Instead, you’ll find yourself almost skimming the code, thinking things like ‘OK, open a file, transform the contents to a sorted list, generate the giant report in a thread-safe way.’ When you have that level of insight into code someone else wrote, there’s no bug you can’t fix and no enhancement you can’t make.

All of this sounds great, right? There’s only one catch: you have to know and use a language’s idioms to benefit. Enter Writing Idiomatic Python. What started as a hasty blog post of idioms (fueled largely by my frustration while fixing the code of experienced developers new to Python) is now a full-fledged eBook.

I hope you find the book useful. It is meant to be a living document, updated in near-real time with corrections, clarifications, and additions. If you find an error in the text or have difficulty deciphering a passage, please feel free to email me at jeff@jeffknupp.com. With their permission, I’ll be adding the names of all who contribute bug fixes and clarifications to the appendix.