[gabemart]

The author consistently compares code language style to literature language style, but I don't think it's a helpful comparison at all.

Literature operates by an intractably complex interaction between the words written on the page and the mind of the reader. Exchanging a single word for another may totally alter the effect of a passage, based on factors like the meaning of the word, the associations the word has for each reader, and the aesthetic appearance and sound of the word.

Moreover, we have no objective way of measuring the effect of literature. We don't have a test that can measure how much more empathetic I become after reading a novel, or how much more I understand the human experience.

Computer code typically has measurable outcomes. While "readability" may still be a relatively subjective measure, we can at least say "these two versions of this function are equivalent" if the outcome is the same - the array is sorted correctly, the transaction amount is calculated correctly, the graph is rendered with the same pixels.

This means that editing computer code is nothing at all like editing literature. The cliff-notes version of Macbeth can never produce the same effect in the mind of the reader as reading Macbeth -- but a function that is subjectively easier to read can be shown objectively to produce the same effect as the original function.

[gregjor]

Good point, I agree with everything you wrote. I didn't intend to compare code language style to literature, maybe I failed to make that clear.

I tried to make the more subtle comparison that some programmers react reflexively to code that doesn't look familiar to them and call it unreadable, the same way that a person unfamiliar with Shakespeare and unprepared (or unwilling) to make the effort to read it will dismiss Macbeth as hard to read.

A person new to Shakespeare picking up Macbeth will find the book challenging because of the antique language, the poetic form and dramatic devices, maybe the historical setting and allusions. A person new to a body of programming code may react the same way, for similar reasons. A reader new to Shakespeare probably knows that the problem lies in their own abilities and patience, not in the book. A programmer new to a body of code will tend to blame the code, in my experience.

[Alex3917]

> A programmer new to a body of code will tend to blame the code, in my experience.

The key thing I disagree with about this is essay is that when it comes to code, there isn't really any reason ever to have anything other than The Hungry Caterpillar or Puppy Peek-a-boo.

There will obviously be differences between projects, but within a single API or whatever, there's no reason why every endpoint shouldn't be coded in exactly the same way. E.g.:

1) Validate user permissions

2) Validate user input

3) Validate business logic

4) Persist results

5) Return data or an error

Within a given project all variables and functions should be named consistently, there should be a consistent style of error handling, etc. Once you've read the style guide and understand how one endpoint works, you should be able to understand how every endpoint works. IMHO saying "I don't understand this, rewrite it" is always the most valuable code review one can give or receive.

If you hired someone to advertise your product on TV and viewers weren't able to understand the ad, you'd probably fire your ad team immediately. I don't see why developers should be held to any lesser standard.

[JamesBarney]

Good writing is not necessarily readable writing. Shakespearean works are good writing, but they are most certainly not easily readable. There is code that is great code because for many other reasons than readability.(Like performance, correctness, robustness)

Easy to read writing is simple and concrete. Code that is easy to understand is also simple and concrete.

Complexity and abstraction push away understanding like two positive magnets. But sometimes readability is worth sacrificing to achieve a separate goal with the code.

[Alex3917]

> they are most certainly not easily readable

They would have been easy to understand by folks who were alive at the time they were written when performed on stage. The only unfamiliar words would have been the ones he coined, but most of those were easy cognates from latin. If Shakespeare wrote the same works today then he'd be a terrible writer.

[soVeryTired]

His comparison to literature falls short in another way: he only considers the great writers. Sure, Dostoevsky is hard to read. But most writers aren't Dostoevsky: some writing is just hard to read because it's bad.

I think a better comparison would be to undergraduate essays. Most of the time the essential points are there, but if the author doesn't know how to write coherently the result is confusing.

[ken]

I don't think that software and literature are inherently different, but I do agree that this post tries to stretch this metaphor beyond its limits.

The first 4 of 6 proposed meanings of "unreadable" are some variant of "It's objectively fine but I don't happen to like it". I wonder if his experience is one where one sees a lot of high-quality but foreign-looking source code.

The article says: "By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov difficult and challenging, but we don’t say “Macbeth is unreadable.”"

When I say some code is "unreadable", I'm very much not saying "It's like that Scottish Play". Shakespeare had a reason to create a convoluted plot for his story. He specifically edited it to be like that. Unreadable source code is usually (IME) a historical accident, often caused by multiple programmers on the same work. Give 3 writers a copy of one of Shakespeare's plays and tell them to each, concurrently, add a new character to the story, and you're not going to end up with a play of equal quality as the original.

I'm not sure I could name a significant program in use written by a single author (Redis might be the closest, in spirit), and some have dozens or hundreds, yet the average book on my shelf here has between 1.0 and 1.1 authors. It's not surprising, to me, that the average program is an incoherent mess, compared to the average book.

Perhaps "Literate Programming" is a good idea, but we've been missing the point. What qualifies a work as Literature is not great typesetting and hardbound publishing and complete sentences, but something simpler: single authorship.

"Should we strive to satisfy the Shakespeare for Dummies demographic?"

My understanding (and I admit it's been a while since I've studied Shakespeare) is that Shakespeare was written for the commoner. The study guides I've seen for it are almost entirely spent defining words that haven't been in common use in 100+ years, and the occasional cultural note. (When's the last time you spoke a word that ended in "-'st" or "-eth"?) If you gave me some FORTRAN-IV code I would struggle at first to understand it, as I do with Shakespearean English, not because any of the concepts are hard but simply the dialect is unfamiliar.

[gregjor]

I can tell you my experience. I see a lot of foreign code, since I work almost exclusively on legacy code (not necessarily old, just not supported by the original developers). Some I would call low quality, most not that bad. I have to spend time and effort understanding the code, even the code I would call high quality.

I get my customers after their original developers have gone, and after multiple other programmers have deemed the code unreadable and unmaintainable. My value proposition comes down to putting in the effort to understand and work with code that every programmer who looked at it before me wanted to rewrite. In ten years doing this kind of work I've only told one customer to start over from scratch.

Fred Brooks talks about "conceptual integrity" and the detrimental effect of too many designers and programmers in The Mythical Man-Month. If you read about the development of Unix and C at Bell Labs you come away with the same impression: a small group of like-minded programmers who achieved conceptual integrity. When only one programmer writes code that integrity usually shows. The more programmers involved the harder maintaining conceptual integrity becomes.

[ken]

It's useful to hear about your background, and based on your article, it's not too surprising. I'm beginning to believe that there's no such thing as a "typical" programmer (no offense!). I know people who write software for aerospace, political dissidents, major web services, healthcare, weekend hackathons, embedded systems, etc., and all of these have completely different kinds of requirements.

Brooks' book is on my shelf (it's one of the N=1 cases!), but I've come to the realization that I'm the only one who actually believes what he says. More than one manager has had it sitting on their desk when they told my team "This project is at risk of running late, so we're adding some additional people..." Never have I ever worked for a manager who agreed to implement anything in it.

Conceptual integrity is an attribute we really have no metrics for (AFAIK), which means it will naturally suffer as a project grows. That's probably why so many managers have no problem sacrificing it for short-term speed. It's a tragedy of the commons. You get credit for adding features, and for creating a new project to replace an old one, but you never see the downside from the gradual removal of conceptual integrity which caused the creation of the replacement project in the first place.

It's also a dramatic difference from literature. When George R. R. Martin is late with the next "Game of Thrones" volume, nobody suggests adding more authors to hit an arbitrary deadline. We'd rather let the schedule slip by a few years than sacrifice any conceptual integrity.

[gregjor]

My experience with Brooks’ Law matches yours: More honored in the breach than in the observance. I also have worked for managers who display TMMM in their office but add people to projects to meet a deadline.

I think decisions like adding more people and sacrificing conceptual integrity and quality reflect a human bias to favor short-term results and to discount or ignore possible future costs.

[brudgers]

It's easy to make measurements of literature. It just turns out that word length and sentence structure and number of chapters aren't that interesting. Most of what gets measured when it comes to code is similar, it's just that it is easy to automate the measurement.

The sorts of things that are hard to measure for literature, like impacts on the lives of individuals, are also hard to measure in code. So code measures what isn't hard rather than what is important (and tends to elevate what is easy to measure to importance as best industry practice). To put it another way, we don't go around measuring how much more emphatic I become after checking in on Yelp, snapchatting my BFF, or listening to fifteen minutes of Ginger Baker Radio on Pandora.

Maybe it is just because our expectations for code are so much lower. And maybe our expectations are so much lower because we don't treat code as literature. We accept code that doesn't change us and our view of the world as good code. Sorting an array quickly is held up as good code despite not having much impact on how we look at the world.

[geocar]

> Exchanging a single word for another may totally alter the effect of a passage

I think that describes code perfectly.

> but a function that is subjectively easier to read can be shown objectively to produce the same effect as the original function.

I think you lost me here.

I've rarely seen two implementations of an array sort that have the exact same effects. Things like how fast it is, and how much memory it uses is important to me.

How many characters on the screen is also important too, although certainly in more of a subjective way.

> The cliff-notes version of Macbeth can never produce the same effect in the mind of the reader as reading Macbeth

And the bubble sort doesn't produce the same effect as quicksort.

I'm not sure I understand what you're saying.

[mistercow]

You seem to be talking about algorithmic differences. Most of the time, when I see someone talking about code readability, they're not talking about the algorithm. The same exact algorithm can be implemented with varying degrees of readability.

[gabemart]

>> Exchanging a single word for another may totally alter the effect of a passage

> I think that describes code perfectly.

I wasn't very clear here: what I meant was that exchanging a single word even for its closest synonym will always change the effect of a passage to some degree, because the intrinsic aesthetic qualities of the word inevitably alter the effect of the word.

This isn't true for code, where refactoring a line of code might change how readable that line is, while conceivably having an identical effect when the line is interpreted, compiled or executed.

[geocar]

I still see symmetry:

That the computer cannot receive joy from code does not mean that I can't; That the computer doesn't experience joy from Macbeth doesn't mean that I don't.

Reading joyful code is a treat. I pity who has not read some code that has brought them joy. And yet, what brings me joy[1], [2] is what the peanut gallery may call unreadable. What then?

[1]: www.nsl.com/papers/origins.htm

[2]: cr.yp.to/qmail.html

Surely something else must be going on.

Kernighan and Plauger, while otherwise dated, has one of the best rules for programmers:

Say what you mean, simply and directly.

Assume the best of the writer of the code you are reading; assume this was them saying what they meant, as simply and directly as they could.

Was it clear in their mind?

Or does it feel like they were muddling through the problem?

If as I am decoding this foreign thing of other people's code, I find my mind repeatedly would put it simpler, cleaner, and clearer, I can complain about the tedium, and mindless repetition in the code, but I'm still not complaining about it's readability.