Readability: Series introduction

Dear readers,

This post is the beginning of a new series on the idioms and style that I use to keep code readable and obvious. I often get positive comments when undergoing peer reviews at Google and externally, so I am going to share such personal style in the hope that it might be useful to some of you. Explaining these ideas to coworkers when I review their code has proven to be useful in the long term.

The posts in this series will, in general, cover generic programming issues that are applicable to any language. That said, all of the examples will be in Python and coming up with such standalone code snippets has proven to be hard. While all of the snippets are fictitious and written for the sole purpose of this blog, they are all inspired in code I’ve had encountered in the past.

There is one little thing that I won’t repeat in every article, but that little thing will govern the whole series: readability and simplicity trump performance and cleverness every single time (unless, of course, your code really, truly is performance critical — and most of the code out there just is not). Keep in mind that a piece of code will be written once but it will be read dozens or hundreds of times by yourself or other people. Also, there is the common saying that the reader needs to be a hundred times smarter than the programmer that originally wrote the code in order to understand what the code does… so keep the code dumb or you won’t be able to parse what you wrote a few months down the road.

And, lastly, don’t worry! Even if this blog has not received any love for the last 7 months, this introductory post will not be left alone without followup articles. I have already written a bunch of the articles in this series to prevent that from happening :-)

Stay tuned.