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

81–90 of 134 posts

Re: What does code readability mean?

#81

Post by [deleted] »

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…

[deleted]

Re: What does code readability mean?

#82

Post by yebyen »

Verdex_3 wrote: post #75
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.

What's the alternative though? Write your code such that people subjectively find it easy to read? Then you have to know the set of all people who are going to read your code AND how their internal (and possibly inconsistent) "easy" function works AND those people can never change personally AND no additional people can be added to that set unless they match someone else's "easy" function AND the sum of all the reade…

I don't think you can solve complex problems and guarantee the solutions are easy to understand. (You've hit the nail on the head.)

But you can absolutely solve many complex problems without straying outside of the set of simple arrangements or simple configurations of purely simple solutions. It may still be hard to understand. It was probably hard to write, too.

It should not be hard to refactor, if at all possible, when the scope of the problem has predictably changed later on.

Re: What does code readability mean?

#83

Post by jeremiep »

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.

Simplicity is about the cognitive overhead to understand code, the simpler it is the less effort it requires to reason about.

That doesn't mean you don't have to learn anything to understand it. Going the easy route usually means dumbing down things and while it can help reading in the moment it definitely doesn't help in the long run as the code evolve over time.

Re: What does code readability mean?

#84

Post by Miss_Vee22 »

jasonmaydie wrote: post #52

I don't like the shakespeare analogy because not every written piece of code is supposed to be a work of art. You wouldn't write an instruction manual like you would write Macbeth. Most of the time there's really no value in writing cryptic code

You are saying that programming is the same as an instruction manual? Programming is art. Nearly every objective in programming will have over a million potential implementations. Personality, wisdom, and mood are in every program (obviously there are some Hello World exceptions) just like artistic writing and nothing like an instruction manual. Machine code is an instruction manual compiled by a computer, a program is a piece of art created by humans.

Re: What does code readability mean?

#85

Post by dang »

stinos wrote: post #44

The author is spot on for 'standard' code styles. However when you enter the realm of crazy code styles (say, all code of the program in one single line, obfuscated code not meant for humans to read and so on), wouldn't we all agree that is in fact, objectively, unreadable? Beacuse actually reading it is simply too hard no matter how skilled and knowledgable you are? (note none of the OP's points cover this, except f…

> wouldn't we all agree that is in fact, objectively, unreadable

No, because there's a rich body of counterexamples in the array-oriented languages (APL, K, J). Everyone who doesn't know these languages immediately dismisses programs written in them as unreadable, but that is far from the truth.

If you spend some time in the alternate programming universe that such languages inhabit, you'll get into your bones the knowledge that readability is relative both to language and to reader, and you'll start to think about simplicity in a deeper way. (By "you" I don't mean you personally, of course, I mean everyhacker.)

Re: What does code readability mean?

#86

Post by chriswarbo »

kstrauser wrote: post #64
chriswarbo wrote: post #57

Earlier quoted context omitted.

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?

> would you say TDD (or any other requirements-driven design process) would avoid that kind of oversimplification?

I haven't thought too much about how such things relate, but my first thought is that TDD seems biased towards oversimplification, since we do 'the simplest thing which makes the tests pass'. If we're testing that Bob's user profile shows the name "Bob", then the simplest thing is to have all profiles hard-coded to say "Bob". To fix this, TDD tells us to add more tests which check different names. That's before we've even begun to consider the hairy details of how names are used in different cultures.

It's a reasonable approach, but it's not "solving" the oversimplification problem, it's just shifting it into the test suite. It's similar to the problem of over-fitting in machine learning models, where we may need millions of input/output examples to narrow-down the intended behaviour.

I think the aggressive refactoring advocated by TDD manages to bias it away from overcomplication.

Re: What does code readability mean?

#87

Post by tigershark »

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 once and read n times by m different people, so there is a huge gain in spending more time in making it simpler to understand rather than spending the minimum time in writing code and leave all the effort to the readers. Readers that, very often, after they become too frustrated, want to rewrite it (and for very good reasons I'd say).

Re: What does code readability mean?

#88

Post by tigershark »

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.

DDD done properly should help in that case.

Re: What does code readability mean?

#90

Post by dbcurtis »

jeremiep wrote: post #83
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.

Simplicity is about the cognitive overhead to understand code, the simpler it is the less effort it requires to reason about. That doesn't mean you don't have to learn anything to understand it. Going the easy route usually means dumbing down things and while it can help reading in the moment it definitely doesn't help in the long run as the code evolve over time.

I agree. Idiom plays a huge role. Example: Python list and dictionary comprehensions can often make the result clear much more easily and succictly than the equivalent loop. But you have to learn Python comprehensions, and the common idioms. And it is possible to take it too far, and write an overly-complicated and obtuse comprehension that is difficult to reason about.

The goal should be code that is easy to reason about, given a reader that is familiar with the popular idioms. I think that for most languages, thoughtfully chosing good names and writing idiomatic code goes a long way to reducing the cognitive load in reasoning about code.

I also find that Python's syntax helps readabilty, and that also decreases cognitive load. Over the holidays I spent some quality time reading up on Rust and starting to climb the learning curve. I'm still at the stage that I find Rust's syntax jarring. It looks like so much ASCII salad. I can't help but think that a little more attention paid to natural syntactic flow would make Rust code easier to reason about for the long haul. Of course, I'm only at the beginning stages of learning Rust idioms -- a fair analaysis can only be done after I have learned them well. But still, it looks like Rust values screen real estate over readabilty, which is a misguided optimization IMHO.

Post reply on HN