What does code readability mean? • Hacker News Board

Re: What does code readability mean?

#21

Post by pjc50 » Mon, Jan 08, 2018, 2:56 PM UTC

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…

I suspect this is as culturally determined as the differing American, European, and Japanese attitudes to rebuilding buildings. European cities typically retain medieval street layout and as many buildings from that time as possible, sometimes even rebuilding to the original style after destructive events. Whereas Japanese houses have a ~30 year lifespan and are routinely rebuilt. And I'm looking up the hill at a castle that accreted between the 12th and 17th centuries.

Just as the street layout will outlive the buildings, APIs tend to be extremely durable and intolerant of destructive rewrites. Consider the Python transition.

Re: What does code readability mean?

#22

Post by seanmcdirmid » Mon, Jan 08, 2018, 2:57 PM UTC

onion2k wrote: post #11

seanmcdirmid wrote: post #4

Earlier quoted context omitted.

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

Yes. But those words don’t come for free, they could be much more expensive than writing the code itself, it’s like trying to teach something rather than just doing it.

Re: What does code readability mean?

#23

Post by [deleted] » Mon, Jan 08, 2018, 2:57 PM UTC

tekstar wrote: post #16

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

[deleted]

Re: What does code readability mean?

#24

Post by gregjor » Mon, Jan 08, 2018, 2:57 PM UTC

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…

I sometimes describe programming as a one-way hash operation on requirements. A lot of information and context gets lost when writing software, and I haven't seen a workable solution to that problem yet.

Re: What does code readability mean?

#25

Post by gregjor » Mon, Jan 08, 2018, 2:58 PM UTC

larschdk wrote: post #8

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…

The biases are real, but readability is perhaps less of an ultimate concern than maintainability and reusability. Both of these depend on the ability of yourself (and others) being able to understand and adapt the code. A bit of foresight in making the life of future you (or colleague) easier goes a long way. Technical debt is real too and the interest can be high.

I have a follow-on article about maintainability taking shape, still in the notes phase.

Re: What does code readability mean?

#26

Post by pjc50 » Mon, Jan 08, 2018, 2:58 PM UTC

olavk wrote: post #19

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

"Unreadable" in this whole discussion should be taken as meaning "requires effort that the reader is not willing to expend", not an absolute. There are very few things that are impossible to read at all, even the notoriously and deliberately unintelligible stunt languages like INTERCAL and brainfk.

Re: What does code readability mean?

#27

Post by artimaeis » Mon, Jan 08, 2018, 3:00 PM UTC

virgilp wrote: post #15

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

Python's PEP 20 utilizes this view on simple v complex, and also covers the idea of complicated.

> Simple is better than complex. Complex is better than complicated.

I've stuck by those two lines of PEP 20 since I learned about them. The object is to write simple code, but it's okay to write complex code if your goal is to avoid complicated (unreadable) code.

Re: What does code readability mean?

#28

Post by tboyd47 » Mon, Jan 08, 2018, 3:00 PM UTC

gregjor wrote: post #24

seanmcdirmid wrote: post #4

Earlier quoted context omitted.

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…

I sometimes describe programming as a one-way hash operation on requirements. A lot of information and context gets lost when writing software, and I haven't seen a workable solution to that problem yet.

This is closer to the root of the problem than saying code is unreadable... the information isn't lost because of the code being produced, it's lost because the developer leaves. Documentation won't work because requirements change faster than they can be documented. I don't know a solution other than just trying to convince that developer not to leave.

Re: What does code readability mean?

#29

Post by olau » Mon, Jan 08, 2018, 3:03 PM UTC

virgilp wrote: post #15

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

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

Re: What does code readability mean?

#30

Post by dablya » Mon, Jan 08, 2018, 3:04 PM UTC

There is a difference between reading legacy code without empathy (sympathy? pretty sure it's empathy) and calling code equivalent of Macbeth as unreadable when Cliff's Notes would do...