Jeff Knupp - Writing Idiomatic Python 3

Theres a famous old quote about writing maintainable software:

While Im not usually one for aphorisms, this one strikes a chord with me. Maybe its because Ive spent my professional career writing software at huge companies, but I have yet to inherit code that didnt eventually cause me to curse the original author at some point. Everyone (besides you, of course, dear reader) struggles to write code thats 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 cant 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.

Its that simple. Idioms in a programming language are a sort of lingua franca to let future readers know exactly what were 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 wont help you understand unreadable code. After all, how can you even be sure the code is doing what the documentation says?

Were usually reading someone elses code because theres a problem. But idiomatic code helps here, too. Even if its wrong, when code is written idiomatically, its far easier to spot bugs. Idiomatic code reduces the cognitive load on the reader. After learning a languages idioms, youll 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 languages idioms, reading the code of a like-minded developer feels like speed reading. Youre no longer stopping at every line, trying to figure out what it does while struggling to keep in mind what came before. Instead, youll 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, theres no bug you cant fix and no enhancement you cant make.

All of this sounds great, right? Theres only one catch: you have to know and use a languages 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 . With their permission, Ill be adding the names of all who contribute bug fixes and clarifications to the appendix.

Cheers,

Jeff Knupp

January, 2013