This week landed in my inbox the book Software Reliability - Principles and Practices, by Glenford J. Myers from the IBM Systems Research Institute. It's a great book with tons of advice that's very relevant today, even though it was published over forty years ago.

The topic being Software Reliability, one might think that the whole book talks about fault tolerance techniques, algorithms, and so on. While that's part of the book, it's not its main theme. The book focuses on the human aspect of programming, and how making improvements there results in software that's more reliable, because it has less bugs, it's easier to maintain, it easier to use for final users, and so on.

In a section about programming clarity we find the following quote:

The programmer’s goal must be writing source code for the primary audience of people instead of machines.

Code that's easier for other humans to understand and read. So when it comes to project maintenance, people can tell what a program is doing. When everything is on fire due to a bug in production, nobody will care how fast that code was written, but people will care if they understand the code, and they are able to fix the issue.

Even in 1976, the idea of writing code for humans to read, wasn't new. In the 1967 Datamation issue there was an article called What A Programmer Does. One of the best unknown articles about best programming practices out there. The author says:

A programmer does not primarily write code; rather, he primarily writes to another programmer about his problem solution. The understanding of this fact is the final step in his maturation as a technician.

A program is a way to instruct a computer how to perform a task for a certain problem, but at the same time, that text is a document that tells other programmers how that problem was solved. How important it is to write readable code! We must write code with our peers in mind, and let the compiler worry of warning us when the computer won't understand something.

The question is how do we make code that's easier to understand? To start there's a lot of advice out there about how to write clean code, or as Myers calls it in his book "Programming Style". He mentions as inspiration the excellent book The Elements of Programming Style by Kernighan and Plauger. The section provides guidelines like "Use meaningful variable names", or "Do not alter the value of the iteration variable within a loop". While I think these are all good advice, I also think we should dig a bit deeper on what it means to write code that's easier to understand.

To that end, I've been reading about literary theory and seeing how to bring learnings from that field into programming. While I won't repeat myself here, I'll link you to the article Lector in Codigo which I wrote as a first introduction to this topic. Recently I wrote an article applying these ideas while reading Visual Studio Code own source code.

This area has a lot to explore, so expect more articles bridging these two disciplines together.

Appendix

The idea of programming for other humans to read has appeared many times. Here's a few more instances:

Knuth talks about it in his 1983 Literate Programming paper:

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

Of course this idea kept coming back. It's part of the 1985 book Structure and Interpretation of Computer Programs:

Thus, programs must be written for people to read, and only incidentally for machines to execute.

Finally in the book 10 PRINT CHR$(205.5+RND(1)); : GOTO 10 Manfort et al. analyze the line of code from the book title, saying that:

the presence of these optional spaces indicates some concern for the people who will deal with this code, rather than merely the machine that will process it.

This idea keeps coming over and over again. We programmers don't seem to learn.