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

11–20 of 134 posts

Re: What does code readability mean?

#11

Post by onion2k »

seanmcdirmid wrote: post #4
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…

There is a lot the context you’ve built up in writing that code that could never fit in the comments (even if thoughts could easily be expressed in words, they would dwarf the code and not directly correspond to it; actually comments can actually make code reading harder in this way). It really isn’t about the language either, at least the programming language, but how the problem was defined and understood in the fi…

There is a lot the context you’ve built up in writing that code that could never fit in the comments

Isn't that precisely what Knuth was trying to resolve when he came up with the idea of literate programming[1]? The fact that you might end up with more words than code isn't a really problem if the end result is better (for some value of 'better') than just the code.

[1] https://en.wikipedia.org/wiki/Literate_programming

Re: What does code readability mean?

#13

Post by ebiester »

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…

Alternatively, we refactor because the right abstraction for the previous phase of the project is not the right abstraction for the current or next phase of the project.

While I do have a respect for Chesterson's Fence as a concept, sometimes the answer to "why is it this way" is "we were learning as we went, and if we did it again, we'd do it another way."

I look at it this way: When you look at an older city built before the age of the car, they were built to be tiny to start, not more than a set of shacks. As the town built wealth, the buildings went to more sturdy, to multi-story, and to more ornate structures. Similarly, our code should start simple and dirty, then cleaned up as it has proved its worth, and then refactored to more robust patterns as the code has built the wealth (and demand) to justify it.

We should consider rewrites, then, as a sign of value, rather than as a sign of the previous programmer's failure.

Re: What does code readability mean?

#14

Post by DavidWoof »

This reminds me of the discussion of "quality" in Zen and the Art of Motorcycle Maintenance, where the class finds that while nobody can exactly define quality, when confronted with high and low quality writing everybody could recognize which was which.

As OP realizes, nobody thinks Knuth's ACP is poorly written even though it's hard. The elegance is obvious, even if the algorithm is hard to understand. On the opposite end, I've come across FizzBuzz implementations from job candidates that I've struggled to follow. I've often seen a 10-1 difference in code sizes for different implementations of the same problem, and while there's edge cases where smaller code can start to become confusing, generally every dev on the team recognizes which of the two is more readable.

I have no problem with the idea that there can be subjectivity in discussions of readability. But the idea that readability is purely subjective, or only has to do with differing styles is ridiculous. In fact, I don't believe for a second that OP really believes this. He wants to make a point about subjectivity, which is fine, but for some reason has chosen to write it in this exaggerated clickbait style.

Re: What does code readability mean?

#15

Post by virgilp »

> “Good code is simple” doesn’t actually say anything. [...] What we call “simple” depends on our experience, skills, interest, patience, and curiosity.

I like Rich Hickey's stance on this: "simple" is objective (antonym: "complex"), whereas "easy" is subjective (antonym: "hard"). Easy depends on skills, interest, patience, curiosity - but simple does not. Simple is about lack of intertwining of concerns. About writing code that can be understood without "bringing in" the entire codebase into your mind. Like, you can understand a pure function just by looking at it (it's simple). If it modifies or uses a global variable, now you have to look at all the places that "touch" that global variable, in order to understand what your function does; the code is thus much more complex.

With that definition - it's absolutely correct to say that the code should be as simple as possible. And that writing simple code is typically very hard.

Re: What does code readability mean?

#16

Post by tekstar »

I once had a developer who consistently wrote unreadable code while trying to be clever. To give him useful feedback I needed to come up with a black and white heuristic for knowing if code is readable or not.

The heuristic is this: Readable code can be explained in English sentences in one pass.

Your code tells a story. When you read it do you introduce the characters in the right order? Halfway through a complex passage do you reference something out of context without explaining it? Give concepts valid names to help the reader build context on your intent.

The best part of this heuristic is that you can get the code author to attempt to read back their own code, and trip over their own convolutions, and realize where there is opportunity to simplify.

We all worked on the same codebase so a reasonable shared understanding of the concepts was assumed.

This blog post throws various situations into the mix to try to be contentious or something but misses the point.

Re: What does code readability mean?

#17

Post by ignoramous »

DavidWoof wrote: post #14

This reminds me of the discussion of "quality" in Zen and the Art of Motorcycle Maintenance , where the class finds that while nobody can exactly define quality, when confronted with high and low quality writing everybody could recognize which was which. As OP realizes, nobody thinks Knuth's ACP is poorly written even though it's hard. The elegance is obvious, even if the algorithm is hard to understand. On the oppos…

I think you're right. And the OP is right, too. There are contexts that OP clearly lays down where they think that programmers are too dismissive and try to stroke their ego at every opportunity and so the excuse of readability needs to be called out for what it actually is. Its an interesting piece, if nothing, the quotes embedded in them are worth their weight in gold. I wouldn't call it clickbait, though.

Re: What does code readability mean?

#18

Post by tboyd47 »

ebiester wrote: post #13
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…

Alternatively, we refactor because the right abstraction for the previous phase of the project is not the right abstraction for the current or next phase of the project. While I do have a respect for Chesterson's Fence as a concept, sometimes the answer to "why is it this way" is "we were learning as we went, and if we did it again, we'd do it another way." I look at it this way: When you look at an older city built…

> sometimes the answer to "why is it this way" is "we were learning as we went, and if we did it again, we'd do it another way."

True, and that's believable when it's people rewriting their own code, but sometimes you'll have people who didn't even try to understand the existing code express a desire to rewrite it.

Re: What does code readability mean?

#19

Post by olavk »

pjc50 wrote: post #3

> By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov difficult and challenging, but we don’t say “Macbeth is unreadable.” What of Joyce's Ulysses ? The thing is, most authors do put considerable effort into readability, because it helps you get read, published and paid. There's an interesting parallel with this article - writer:programmer :: critique group:code review. > Programmers, prone to in…

Ulysses is not unreadable, it just takes a lot of effort. For programming, the criteria is not if it is hard to read, but whether the same thing could be expressed in way that would be simpler and easier to read. But I not sure to what extent this could be applied to poetry, since the expression in language is in itself "the thing".

Re: What does code readability mean?

#20

Post by gregjor »

DavidWoof wrote: post #14

This reminds me of the discussion of "quality" in Zen and the Art of Motorcycle Maintenance , where the class finds that while nobody can exactly define quality, when confronted with high and low quality writing everybody could recognize which was which. As OP realizes, nobody thinks Knuth's ACP is poorly written even though it's hard. The elegance is obvious, even if the algorithm is hard to understand. On the oppos…

I had Zen and the Art of Motorcycle Maintenance in mind when thinking about readability, because that describes one kind of quality we care about.

I don't think I wrote that "readability is purely subjective," I certainly didn't mean to imply that. I did mean to make a point about subjectivity.

Sorry you didn't like the style. I write articles because I enjoy writing and I think I have ideas worth sharing. I don't have ads or affiliate links on my site, so I have no incentive to post clickbait.

Post reply on HN