The pleasure of reading code, good or bad by Philippe Barbe 16 Jun 2021

The work of a Data Scientist is to build and apply knowledge and systems that produce insights to support decision making. The primary tool used by Data ScieThe work of a Data Scientist is to build and apply knowledge and systems that produce insights to support decision making. The primary tool used by Data Scientists to do this work is computer code.

Reading code can be both an enjoyment and a chore.

Facing a ream of code spread over hundreds of files to understand how it is structured and what each piece does, is not always an easy task. Good programmers know how to structure, write and document their work to make it easy to navigate, read, and most importantly, conveys their intent very clearly.

Good programming teams have standards that ensure consistency of style across team members, and good leadership is reflected in the ability to structure a project.

Although reading bad code is not a very pleasant experience, I’ve come to enjoy reading code… good, bad or ugly… because it is a very human experience that I would like to share with two different audiences:

• non-coders, to explain what coding is about beyond making a computer doing certain operations that makes it worthwhile to read,
• coders not happy about having to read bad code, a different perspective that may turn a bad experience into a more positive one.

If you are not a programmer, to get a sense of the kind of variance that exists when reading code, randomly select 50 books at a library and open each to a random page. You will see a wide variety of print sizes, character, line and paragraph spacing, beautiful and ugly typography, some with pictures, some without, some with lots of headers and sub-headers, some with no headings. Some will attract and draw you in, others will repel you.

Code is no different. How does it look? Is it inviting or repellent?

Open one file and it is beautifully set, nicely indented, with a powerful visual arrangement driven by logic and rules akin to typographic ones and the visual aesthetic seems miraculous. How these computer instructions make such a visual feast is a mystery. Like most extraordinary paintings, I stare at it, without reading it, admiring its elegance. This is inviting! I am going to have a good time reading this.

Open another and we see chaos. Nothing appears organized. It’s is hard to look at, even painful sometimes, let alone read!

Either way, behind these lines of code is a human who wrote them.

And that is where the interest and pleasure kicks in for me as I wonder… Who is this person who created this? Are they young and inexperienced or coding veterans? What does their creation reveal about their thinking process? And, if it’s hard to read… Is there some way to help? How can this be made better? What is the first thing to start improving that will give the biggest bang for the buck?

Programmers often embed lines in their code called “comments” that serve no purpose for the machine since they are not executed but are only intended to make the code more readable by humans. I find such comments interesting, not only for what they say about the program code, but also for what they say about the person who wrote them.

Some comments are economical, to the point, enlightening. This is thoughtful programming. Thank you, I am so grateful.

But, what does a comment like this say about the writer? “# COMMENT: the next paragraph follows the previous one”. Does this person have hard time grasping the notion of what a paragraph is? Is the comment inserted without thinking simply to comply with a requirement for annotating the code? Did someone review this code?

As I read “bad” code so many questions pop up as I become curious to know more about the author and their struggles. Beyond the person, the code says something about the organization, how it is managed, how do people work together? What sort of organization are they in that they end up writing these strange comments?

Occasionally, a line is useless, such as

456 x = 2

457 x = 2

Why is line 457 repeating line 456?

A repetition of x = 2 is not a typo which would usually generate a bug, and this repetition does not. Someone forgot to take off that line. What was this person thinking? Was it written at the end of the day? Tired? There is something amusing in this. Maybe this person wrote it for fun. Would it be repeated 3 times if it were x = 3?

The choice of names offers clues about the author. Some go economical, pmnt = 1000, assuming that the reader knows standard abbreviations in the business. Some go regular, payment = 1000, sober, simple. Some go precise, payment_for_work = 1000, adding context. Some go furtively, p = 1000, maybe paid by the line. And some show where they come from, payement = 1000.

The structure of the code also reflects the comprehension of the problem the program solves. By isolating this function, by creating that class, the programmer asserts the significance of an operation or a concept. Code is not just a neutral list of tasks for a computer to perform, it expresses the point of view of a writer. It is an opinion.

Two programmers may write code that achieves the same result but their different ways of writing that code expresses their difference of views.

Like political commentary there are mainstream views, and some less mainstream which is sometimes good, sometimes less so. Unlike political commentary, code is not an editorial because it aims to achieve a result that can be tested. One knows if a code works or not (although defects may appear over time).

Still, how code is structured reflects a vision on the problem, the relevant concepts, its important parts and how the problem has been thought through, all of which impact its current relevance and future durability.

Conclusion

Programs may be executed by machines but they are written and read by humans. As such they may be the only form of communication that aims at both machines and humans. Beyond what code instructs a computer to do, for me, the pleasure of reading code is the connection to its creator. Far from the deterministic perfection of the machines that execute it, to feed these machines, the person who wrote the code took a stand on a problem.

Programs convey intent, opinions, and reflect the ability of their writers to control mindless machines flawlessly and carelessly executing billions of instructions each second. The authors wield immense power as their code controls many of the processes that produce the goods that we consume, making their code visible and invisible parts of our existence.

Every person who codes reveals a part of themselves telling enough to feed the imagination and make me want to know more about the author. Behind the precision and accuracy of those computer instructions is a person who is impossible not to like for the qualities, or the flaws, their code expresses.

Admiration and empathy feeds my desire to know both excellent and not so excellent coders. Reading code is an experience that become enjoyable when we view it as an expression of the humanity of the author that connects them to the reader as much as their code connects the computer user to the machine. machines but they are written and read by humans. As such they may be the only form of communication that aims at both machines and humans. Beyond what code instructs a computer to do, for me, the pleasure of reading code is the connection to its creator. Far from the deterministic perfection of the machines that execute it, to feed these machines, the person who wrote the code took a stand on a problem.

Programs convey intent, opinions, and reflect the ability of their writers to control mindless machines flawlessly and carelessly executing billions of instructions each second. The authors wield immense power as their code controls many of the processes that produce the goods that we consume, making their code visible and invisible parts of our existence.

Every person who codes reveals a part of themselves telling enough to feed the imagination and make me want to know more about the author. Behind the precision and accuracy of those computer instructions is a person who is impossible not to like for the qualities, or the flaws, their code expresses.

Admiration and empathy feeds my desire to know both excellent and not so excellent coders. Reading code is an experience that become enjoyable when we view it as an expression of the humanity of the author that connects them to the reader as much as their code connects the computer user to the machine.