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

61–70 of 134 posts

Re: What does code readability mean?

#61

Post by mannykannot »

seanmcdirmid wrote: post #48
mannykannot wrote: post #40

Earlier quoted context omitted.

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…

You mean waterfall right? Ya, then I guess. If the program is understood before it is written (waterfall), then you merely write down these ideas along side the code. If programming plays any matter into evolving the design (as you say, “hunches” that go into a feedback loop), then this will break down quickly. Edit. Never mind you mean afterwards. But is the assumption that design can occur independently of programm…

My description of blind trial-and-error programming is not a veiled reference to agile development, if that is what you are thinking - it is, rather, an anti-pattern in development that is neither agile nor waterfall. There is nothing in agile that says you should just try things until something seems to work. No line of code gets written without the programmer of having an expectation of it making some contribution to the solution, and the issue is how well-founded that expectation was.

Update: Perhaps the canonical example of non-agile trial-and-error programming without well-founded expectations is the programmer who is putting delays in various parts of his program in an attempt to fix a concurrency error.

One's understanding of the program does not necessarily break down under iterative development, as, if you are doing it right, each iteration improves your understanding.

The usefulness of documentation does depend on the complexity of the problem, but in the opposite sense: programs solving simple, well-defined problems do not benefit much from additional explanation (there's not much to say that is not obvious), but the more complex things get, the more it helps.

Re: What does code readability mean?

#62

Post by rimliu »

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…

There is readability and there is understandability. Which may or may not be the same. Just like text you may have text that is cramped with very long lines and no line spacing, maybe no word spacing—it may be very hard to read it but once read it can be easy to understand. OTOH you can have a nicely typeset text which is impossible to understand.

And if you talk about code there is also changeability. Which is somehow at odds with understandability. To make code easier to change you must move to abstractions, and more abstractions make a code more difficult to understand—but easier to change.

Re: What does code readability mean?

#63

Post by rimliu »

crdoconnor wrote: post #59
geokon wrote: post #51

Earlier quoted context omitted.

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

My intuition tells me that good code is when I reach a localized minima balancing coupling, amount of code written, expressive density of the code, clarity of purpose and ability to fail quickly under invalid conditions. There are often times when I could make the code simpler but it would be longer and vice versa and my decision about which one to pick is purely personal.

https://www.sandimetz.com/99bottles/ is all about that. It starts with a few different ways to solve the same problem and then goes into comparing them using chosen criteria.

And then it goes on to implement the solution using TDD. Very underappreciated book, imho.

Re: What does code readability mean?

#64

Post by kstrauser »

chriswarbo wrote: post #57
kstrauser wrote: post #36

Earlier quoted context omitted.

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.

I've come across these meanings too, and they're the ones I use. Complexity is a property of the problem; complication is a property of the solution. Whilst over-complication is bad (e.g. your Rube Goldberg example), so is being simplistic (not enough complications to handle the complexity). Examples of simplistic solutions can be found in all of those "What programmers don't know about FOO" articles (human names, ti…

That's a great point. I've given approximately zero thought to this, but would you say TDD (or any other requirements-driven design process) would avoid that kind of oversimplification?

Re: What does code readability mean?

#65

Post by HeroOfAges »

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…

I'm of the opinion that companies should rewrite as much of their codebase as often as possible. Given the difficulty of trying to understand code written by someone else, why shouldn't production code be considered immutable?

Re: What does code readability mean?

#66

Post by seanmcdirmid »

mannykannot wrote: post #61
seanmcdirmid wrote: post #48

Earlier quoted context omitted.

You mean waterfall right? Ya, then I guess. If the program is understood before it is written (waterfall), then you merely write down these ideas along side the code. If programming plays any matter into evolving the design (as you say, “hunches” that go into a feedback loop), then this will break down quickly. Edit. Never mind you mean afterwards. But is the assumption that design can occur independently of programm…

My description of blind trial-and-error programming is not a veiled reference to agile development, if that is what you are thinking - it is, rather, an anti-pattern in development that is neither agile nor waterfall. There is nothing in agile that says you should just try things until something seems to work. No line of code gets written without the programmer of having an expectation of it making some contribution…

There are plenty of cases where programming helps you explore the design space, where you have little knowledge about the APIs you are using, so you poke them a bit here and there, obtaining experience in knowing how to use them in the way that you need (because, let’s be honest, even the best frameworks have defficiencies in their documentstion, if you decide to read the docs at all). Likewise, it isn’t that weird to write some code that you know is broken so you can fix it in the debugger where live values and feedback are available. Heck, many people code from interpreters these days which are as exploratory as you can get!

Of course, we can argue about different kinds of programming have different needs. Prototyping doesn’t require documentation and so can move much faster than product development, for example. The cost of not documenting is a huge win for the prototyper, allowing them to try out and throw away designs while worrying less about sunk costs.

The design has to come from somewhere, after all. A design team with prototyping resources really values those resources.

Re: What does code readability mean?

#67

Post by onion2k »

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.

it’s like trying to teach something rather than just doing it

If you work on a team a lot of your time is spent 'teaching' (explaining) your code to other developers. Or teaching yourself about it when you come back to something you wrote 6 months ago. Or 'teaching' a QA person your logic to understand where a bug is coming from. Or using your code to literally teach a concept to a junior developer.

Writing documentation can feel like teaching rather than just doing, but that's not necessarily a bad thing if you're working on something that other people need to understand.

Re: What does code readability mean?

#68

Post by gregjor »

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

Totally agree. It's a lot of work though and can be humbling to find out that the previous people weren't complete idiots. Reading code also doesn't really get rewarded. It's easier to declare the work of people who aren't there anymore as bad and rewrite everything.

Throughout most of my career reading and maintaining code got fobbed off on the new programmers and the less skilled. Maintenance programming has a bad reputation, partly because it requires reading and figuring out someone else's code.

Now I make a living reading and maintaining code no one else will touch. Lots of companies can't afford to rewrite a mostly-working system, or they can't take the risk. I found a niche doing maintenance work and now I enjoy fixing what other programmers have said they can't maintain. Freelance maintenance work pays just as well as green-fields development and has fewer customer hassles, too.

Re: What does code readability mean?

#69

Post by gregjor »

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…

That's called the telephone test. From The Elements of Programming Style (referenced in my article):

"Use the telephone test for readability. If someone could understand your code when read aloud over the telephone, it's clear enough. If not, then it needs rewriting."

I agree that the telephone test heuristic gives you an idea of readability, but in 1974 Kernighan and Plauger assumed someone one the other end of the phone who knew Fortran or PL/I.

Trying to explain a moderately complex class hierarchy or a factory function or a closure over the phone would prove challenging. I could explain the purpose of the code at a level someone else could understand, but they might not recognize the implementation when looking at the code.

A few years ago, doing maintenance on an abandoned production system, I came across a function with the comment "Produce a unique six-digit identifier that doesn't start with 0". The original programmer could have explained that to me over the phone, but his implementation (in PHP) was not clear at first or second glance. I expected this:

  $id = rand(100000, 999999);
Instead the function started with a loop to get the first digit:

  while (true) {
      $first = rand(0, 9);
      if ($first != 0) break;
  }
I'm not making this up.

Then another loop to pick five more digits in the range 0..9. Then a database query to see if that ID was used, and if it was the function called itself recursively. I'm not kidding.

So while I would have understood the problem described over the phone, I didn't recognize the implementation at first sight. If the programmer had read the code to me over the phone I might have assumed I was missing some requirement that led to this overly-complicated implementation. Not all of the code looked like this so I don't know how the original programmer got wound around the axle on this function.

Re: What does code readability mean?

#70

Post by vec »

virgilp wrote: post #38
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.

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…

"Which is the better painting, Van Gogh's Starry Night or Seurat's La Grande Jatee?" is a deeply subjective question.

"Which is the better painting, Van Gogh's Starry Night or a kindergartener's watercolor of their family?", on the other hand, appears to have a correct answer.

There are multiple competing definitions of "simple" with respect to code and multiple kinds of simplicity that often have to be traded off against one another, and reasonable programmers can and do disagree about which compromises to make and where. Code quality (including, but not limited to legibility) is in many regards a subjective endeavor.

That doesn't mean, though, that all decisions are equally justifiable. Trust your sense of aesthetics. It's usually trying to tell you something important, even if you don't know how to put it into words yet. With subjective endeavors there is no perfect, but there is usually better. Chase that.

Post reply on HN