Repost - Code is read more often than it is written

2020-06-09

Back in 2016, when I was a young programmer, I stumbled into Python. I still have some affection for the language, but I haven't gotten to use it beyond hobby projects yet. While I may have just stumbled on it, I stuck with it because the very nature of the language. It's syntax captivated me. There was a certain elegant simplicity which I hadn't witnessed before. And it was in such a mood that I read PEP 8, and Guido's insight struck home.

Code is read more often than it is written.

At the time I was on vacation, but I began furiously scribbling notes, which I eventually posted. My intent then, was to share my 'discoveries' with anyone who'd listen. The goal then was the same as it is now: Give something of value to our community. While my personal situation might keep me from creating new content for a while, I still mean to give something of value. So I'll be re-posting my best content. Just reposting, of cource, isn't going to drive that value, but please stay tuned! I've expanded a bit on each of these posts as my experiences have deepened. Now, without further ado, 'Code is read more often than it is written'.


At first glance, this would seem an obvious statement. And it is in a way. When Python language creator Guido Van Rossum created Python, he did so with this thought in mind. As a result, the culture of Python is partly molded around “readability counts”.

The more I thought that statement, the more I realized the marvel it held. ‘Code is read more often than it is written’. If asked to choose between reading and writing, I would have said the same. And yet I realized now, that much of the code I have read, and some of the code I have written does not show this. I wondered, why did my behavior, and that of my peers, not match what I knew to be true? If we believed that code was read more often, they why is so much of our code so hard to read?

At the core, our behavior remains unchanged because this quote is only an observation. There is not imperative contained in it. Without the means of an imperative, the observation cannot turn into an action. Instead the reader would need to derive ‘Code ought to be easily read’ from ‘Code is read more often than it is written’. I trust most would be equal to the task, given a basic desire to optimize.

When I first discovered this, I did not pay it nearly enough attention. I went blithely on my way. Some time later, during the quiet of a vacation, the thought came storming back. I was left dumbfounded. How could I have not seen it earlier? I realize now, it was because I had not given my self enough time to think. With the lighter load during vacation, I was able to think, and so naturally the thought came.

This moment of serendipity also encouraged other considerations. Specifically, what other imperatives had I missed with casual observations? I quickly realized this is dark territory. It would be difficult to turn every observation into a possible imperative. Worse still, these observations might be biases, leading to bad imperatives. Or they might be too weak to lead to a meaningful imperative.

In all cases, the question remains, what have I missed? I believe, especially in software, that we are caught in a rush to develop, to implement, and to finish. As a result, we do not give ourselves time to ask, ‘Is this the best way?’ Business demands that we move with purpose, and that is a reasonable demand. But for the best results, we need time to consider if we go in a way that will deliver us to the goal we seek. I will continue to look for miss-able observations may turn out to change everything.

Addendum:

While drafting this article, two other examples of ‘observation leading to imperative’ appeared. The first was fictional, from Foundation and Earth by Isaac Asimov. In the book, the protagonist remarks with surprise at the neural interface to a computer. Instead of being an over-the-head affair, it was through the hands. His realization was that humans sense and interact with the world through their hands. I may revisit this in a later branch of this discussion on design.

The second example, sprouted from the first, specifically interaction and design. Recently the IoT movement has brought integration to our homes. In particular, the voice-interaction, such as Amazon’s Echo or Google Now. I observed that these devices extended a natural principle: ‘Humans use their voice to make their wishes known.’


P.S. You should check out PEP20 'The Zen of Python'. Even if it's aimed at Python the principles in it are broadly applicable, and very well stated!