Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What does code readability mean?

typicalprogrammer.com

Post reply on HN
Print view View original

91–100 of 134 posts

Re: What does code readability mean?

#91

Post by dbcurtis »

geokon wrote: post #51
olau wrote: post #29

Earlier quoted context omitted.

> With that definition - it's absolutely correct to say that the code should be as simple as possible. Yet, it is humans who need to read it. This is the end goal. If you rewrite the code to satisfy a theoretical objective criteria of simplicity, but end up with something that people reading the code find harder to read, then you have failed. It's the same when you design a UI.

Well humans reading your bit of code is not the only end goal. My intuition tells me that when I've refactored something to be simple-but-hard it ends up making more maintainable code. There is less state being maintained, less lines of code to maintain, less coupling. Yes it requires a bit more time to understand, but there is also less stuff to understand . Bad code and bad decisions snowball into bad projects

Yes, simply optimizing for less state and fewer side-effects, and letting the chips fall where they may, is 80% of the benefit. Most of what I do is realtime and/or robotics. Basically, varitions on:

  power_on_self_test()
  while True:
    recover_from_everything_that_has_gone_wrong_so_far()
If the only rule you enforce is making sure every piece of state has a damn good reason for existing life is improved.

OK, on re-read this sounds like more like a rant, and less like a philosphy of life. Oh well.

Re: What does code readability mean?

#92

Post by ken »

gabemart wrote: post #79

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…

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.

Re: What does code readability mean?

#93

Post by geocar »

gabemart wrote: post #79

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…

> 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.

Re: What does code readability mean?

#94

Post by gregjor »

gabemart wrote: post #79

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…

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.

Re: What does code readability mean?

#95

Post by gregjor »

ken wrote: post #92
gabemart wrote: post #79

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…

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…

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.

Re: What does code readability mean?

#96

Post by mistercow »

geocar wrote: post #93
gabemart wrote: post #79

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…

> 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…

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.

Re: What does code readability mean?

#97

Post by gregjor »

tigershark wrote: post #87
tboyd47 wrote: post #2

This is a thought-provoking and well-written blog post about programmer biases when it comes to reading, and judging, other people's code. The author is making the point that code readability is ultimately in the eye of the beholder. I've come to share the author's views, and I have to say I don't hear it said much in programming culture. At most places I've worked, there's this culture of constant refactoring under…

Only if you write shitty code it's 10 times easier to write it than to read. When I write my code I use much, much more effort to try to express clearly my intent and what it is doing, and in that case it's much easier to read it than to write. I think that we can easily say that good code is very difficult to write and very easy to read, bad code is very easy to write and very difficult to read. The code is written…

We all think that we write our code so other programmers can read it, and we believe that because while we have the code in our heads we don't have any problem reading it.

I don't question your intentions or abilities, but the fact remains that a whole lot of programmers find almost every piece of code they didn't write hard to read. Or they say that -- I think they mean they just don't like the look of it, or they can imagine writing it differently.

Re: What does code readability mean?

#98

Post by soVeryTired »

gabemart wrote: post #79

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…

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.

Re: What does code readability mean?

#99

Post by gabemart »

geocar wrote: post #93
gabemart wrote: post #79

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…

> 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…

>> 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.

Re: What does code readability mean?

#100

Post by brudgers »

gabemart wrote: post #79

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…

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.

Post reply on HN