What does code readability mean? • Hacker News Board

Re: What does code readability mean?

#31

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

tboyd47 wrote: post #28

gregjor wrote: post #24

Earlier quoted context omitted.

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.

Right. Developers are the real resource/investment and all code rots. At least for now.

Re: What does code readability mean?

#32

Post by markild » Mon, Jan 08, 2018, 3:10 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".

Only in the context of writing as an art form.

There are many other scenarios where writing is used as tool simply to convey meaning. Like this comment.

Re: What does code readability mean?

#33

Post by Quarrelsome » Mon, Jan 08, 2018, 3:13 PM UTC

I work on a system where arbitrary property access results in database round-trips. So the following code:

foreach(var b in a.Bs) { if(b.Data != null) { ThisIsInteresting(b); } }

results in a.Bs.Count + 1 round-trips to the server and then database if these fields have not been accessed before. (a.Bs is one and b.Data != null is one as well).

This is a fine example of what I'd call "unreadable" code because there is so much activity that is implied by actions that in other systems are completely innocent and well isolated.

Also there is the point of cognitive load. If your entire application was simply one function it is technically "readable" but the cognitive load of trying to work out what is in scope and what might change a given variable is too high to read without extraordinary effort. When working in such systems (as I have before) you HAVE to rewrite it to even start reading it because a human memory cannot hold all that information at one time.

I think brushing it all of this off as "the reader isn't reading well enough" is disingenuous.

Re: What does code readability mean?

#34

Post by virgilp » Mon, Jan 08, 2018, 3:14 PM UTC

artimaeis wrote: post #27

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.

That is a strange and "unnatural" (for me) use of the word "complicated". Cynefin[1] defines 'complicated' as "known unknows" and 'complex' as 'unknown unknowns'. The idea is that complicated things are non-obvious, but they are understandable (with expertise, you get the relationship between cause and effect). With complex, full cause & effect cannot be known apriori, it's just observable after the fact.

That somewhat resonates with the definition that complex (code) is about intertwining - 'complex' is problematic because as things get more and more complex, you can have only a local understanding, and can't possibly hope to grasp all the implications of a code change. This suggests that "complicated" is something that is "somewhat complex, but still manageable with sufficient expertise/domain knowledge". I tend to use "complicated" to denote something that has inherent complexities (due to the nature of the real world); and "complex" to denote something that is artificially complex, due to ... well, lack of thought into making it as simple as it could be. In that sense, I view "complex" as being definitely worse than "complicated"

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

Re: What does code readability mean?

#35

Post by LanceH » Mon, Jan 08, 2018, 3:15 PM UTC

You'll know it when you see it.

Re: What does code readability mean?

#36

Post by kstrauser » Mon, Jan 08, 2018, 3:20 PM UTC

virgilp wrote: post #34

artimaeis wrote: post #27

Earlier quoted context omitted.

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.

That is a strange and "unnatural" (for me) use of the word "complicated". Cynefin[1] defines 'complicated' as "known unknows" and 'complex' as 'unknown unknowns'. The idea is that complicated things are non-obvious, but they are understandable (with expertise, you get the relationship between cause and effect). With complex, full cause & effect cannot be known apriori, it's just observable after the fact. That somewh…

I see it the opposite way. Some things are inherently complex, like heart surgery or launching a rocket. There are many things that have to work together perfectly or the whole thing goes south.

Complicated to me means that complications have been added where they weren’t needed. A Rube Goldberg machine solves a simple problem that has been complicated.

Re: What does code readability mean?

#37

Post by lambic » Mon, Jan 08, 2018, 3:21 PM UTC

I often refactor code as a way to understand it; working through the logic and rewriting it in my own style helps me get a good grasp of what the original code was doing.

Sometimes I throw away that refactoring if I realise that the code I was having trouble understanding was actually fairly well written and I just need to sprinkle in some comments.

Re: What does code readability mean?

#38

Post by virgilp » Mon, Jan 08, 2018, 3:23 PM UTC

olau wrote: post #29

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.

But if you don't have an objective criteria of simplicity, how can you even hope to have universal agreement of what is "simpler"?

Humans are complicated beasts. Saying "people find the code harder to read" doesn't help me know what I should do. If I have no objective criteria, then it must be subjective, and then all that "simple" means is that "this is easiest for me right now" - which, from experience, I claim to be a very unlikely path to produce code that multiple people agree to be "simple". (except if the problem was trivial to begin with - but then, who cares?)

Re: What does code readability mean?

#39

Post by dahart » Mon, Jan 08, 2018, 3:26 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…

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

This is true! In fact there's a lot of that, in my own experience. Rewrites are probably most useful on code you wrote, rather than on someone else's, and right when you realize what went wrong, while you're still intimately familiar with the old code.

I've watched two different companies follow the "things will be so much better if we rewrite" logic and rationalize large scale rewrites that cost millions, and years, and failed to achieve the aims of doing it better the second time.

Rewrites should be considered a sign of value only if we actually learned from out mistakes, only if both everything wrong with the old code and everything right with the old code are well understood. If you rewrite anything substantial before that, you're just guessing, and you're most likely (in my experience) going to suffer taking longer than you want and making the same mistakes again. I've seen that happen to many very smart people.

So there's a balance. Rewrites are sometimes valuable, but not automatically valuable. Sometimes rewrites are very harmful. The best chance you have of knowing which one is to read lots and lots of code before you start, to make absolutely sure that the code you're replacing is never being replaced only because the readers didn't understand it or didn't like it's patterns.

OTOH, if you have complete test coverage in place before a rewrite, you can freely annihilate and redo large portions of code without having to study too hard.

Re: What does code readability mean?

#40

Post by mannykannot » Mon, Jan 08, 2018, 3:28 PM UTC

seanmcdirmid wrote: post #22

onion2k wrote: post #11

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

This is not the right model for assessing the cost of documentation. If the program is in any sense designed (as opposed to being assembled and modified on the basis of hunches until it appears to work), then the ideas expressed by those words must have been known no later than the completion of the work. Therefore, the cost of documentation is that of writing down these ideas, and the cost of not documenting is the cost of repeatedly reverse-engineering them from the code.

It is my experience that you can markedly improve the speed and accuracy with which a newcomer can understand a code base with supplementary documentation of considerably fewer words than are in the code itself - so long as those words are well-chosen, and focus on the programmer's intent.