Hacker News Reader

Comment by mojuba | Hacker News Reader

> Is the software easy to take in at a glance and to onboard new engineers to?

This is not as easy as it sounds. Who are those "new engineers", juniors? 10 years of experience? 30 years? What's your requirement?

"Readability" is such a wildcard, with a whole range of acceptable levels from zero to infinity. Readability is a non-concept really. Maxwell's famous equations are readable to some and absolutely impenetrable to the rest of us.

So when someone says "code should be readable", to whom exactly?

View on HN

Readable code is code that has empathy for the reader and tries to minimize the cognitive load of interpreting it. That's one of the goals of abstraction layers and design patterns.

Yes, it's all subjective, and depends on the reader's expertise and existing familiarity with the codebase. But arguing that code readability isn't at thing, because it's subjective, is an absurd take. Would you claim that Joyce's Ulysses is equally readable as Seuss's The Cat in the Hat?

I see this argument pattern a lot, so looked into what the name is. Apparently it's called Sorites paradox: https://en.wikipedia.org/wiki/Sorites_paradox or the "continuum fallacy" in which something that's continuous is dismissed as not existing because we can't divide it into clear categories.

Did someone claim readability does not exist?

> Readability is a non-concept really

Yes.

Readability without a clarification is a non-concept. You can't say "X should be readable" without giving some context and without clarifying who you are targeting. "Code should be readable" is a non-statement, yes.

Add "to most developers" for context and you'll probably get exactly what original claim meant.

It's not a non-statement. Rich Hickey explains it well, readability is not about the subjective factors, it's mostly about the objective ones (how many things are intertwined? the code that you can read & consider in isolation is readable. The code that behaves differently depending on global state, makes implicit assumptions about other parts of the system, etc - is unreadable/less readable - with readability decreasing with number of dependencies).

It can be further refined to

"to most developers who are most likely to interact with this code over its useful lifetime."

This means accounting for the audience. Something unfamiliar to the average random coder might be very familiar to anyone likely to touch a particular piece of code in a particular organization.

>"Code should be readable" is a non-statement, yes.

Oh, I completely disagree here. Take obfuscation for example, which you can carry on into things like minimized files in javascript. If you ever try to debug that crap without an original file (which happens far more than one would expect) you learn quickly about readability.

I didn't say readability is subjective. I'm just asking, when someone says "code should be readable" without any clarifications, what does it really mean?

Big companies may actually have an answer to that: "since we require at least 2 years of experience in the area from new hires, all code should be readable at that level".

However startups may prioritize something else over readability at that level, for example: move fast, produce the most minimalist code that would be easy to maintain for people like you.

My point being, "code should be readable" should always come at least with a footnote that defines the context.

>> Readable code is code that has empathy for the reader and tries to minimize the cognitive load of interpreting it. That's one of the goals of abstraction layers and design patterns.

Usually that means something less than "perfect" from the perspective of the writer. Applying to much DRY, SOLID, DI and other "best practices" will make it very hard to understand. Pretend you have about 20 less IQ points than you actually have when writing the code - you will thank yourself when you come back to it.

Reminds me of someone's quote:

> Reading -- and understanding -- code requires twice the brainpower of writing code. So if you used every bit of your intelligence to write 'clever' code, you won't be able to maintain it because it requires twice your intelligence to read it again.

Einstein's words are oh so suitable as well:

> Everything should be made as simple as possible, but not simpler.

The trap people fall into is calling The Cat in the Hat unreadable compared to Joyce's Ulysses because The Cat in the Hat they're reading is written in German and all they understand is English.

Theere are two quite a widespread classes of not readable code:

Some code is not readable by _anyone_. That's not readable code.

Some code is readable by its author only (be it AI or a human). That's also not readable one.

Saying readability is not a concept is really strange.

I have a formal proof for you that it is a non-concept. If code can be read and interpreted by a computer, it means it can in principle be read by a human. There are of course some edge cases like obfuscated JavaScript or binary executable that some people are able to read and understand.

The question comes down to being reasonably readable and we are back to square one: "reasonable" is very relative. In my early days I could read 8086 binary code (in hex) and understand what it does, it was literally at the very edge of readability but it wasn't unreadable.

Sure, but we do agree that Hello World is MORE¹ readable in Python compared to the equivalent program in say Brainfuck?

  print("Hello World")

  ++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.

¹: more readable means easier/faster to read for most human beings that know the language

I can't reasonably read whether this comment agrees or disagrees with the parent

You are using a different definition of readable than most people are. Most people are using it to mean "the target audience can read and understand the code, and do so in a way/context that allows them work with it". Your definition seems to be "can read the symbols on the screen".

I can read Assembly. I can, in some cases, figure out what that Assembly is doing. I can not, however, work productively with it. I can read Assembly but would not consider it readable.

Readability to a certain degree is heavily influenced to the reader's experience and familiarity.

If somebody has spent lots of time in specific patterns he/she'll find them natural to read and mentally process.

To others, they'll be unreadable.

I'll have to disagree.

Developers coming from functional programming and developers coming from C programming, for instance, have very different definitions of "readable", and neither is obviously wrong.

Similarly, developers used to channel-based, async-based or mutex-based concurrent programming will all have very different criteria for "readable" code, again none of them obviously wrong.

Those are just paradigms, ways of solving problems. There’s a difference between familiarity and readability. Sometimes you have to learn stuff before understanding them. Readability is how easy it is to do that, given familiarity with the base concepts that the code use.

You are correct.

Yet it's pretty easy to find people who consider that `map()` or `filter()` are simply not readable – or, on the other side of the aisle, that having a loop variable is detrimental to readability.

And of course, these criteria change with time, industry and programming language used.

Speaking of those equations, as he wrote them they were considered rather impenatrable and the modern ones are considered much more beautiful and 'readable' but that was the work of Heaviside and others.

> Readability is a non-concept really. Maxwell's famous equations are readable to some and absolutely impenetrable to the rest of us.

When we talk about a language's readability we're typically talking about 'accidental complexity', to use Brooks' term, [0] and not the 'essential complexity' of the problem being solved. For a hairy enough algorithm, even pseudocode can be difficult to understand.

Readability applies in mathematics too, as a bad notation may make formulae unnecessarily difficult to comprehend.

> So when someone says "code should be readable", to whom exactly?

I'll have a go: to another competent engineer familiar with the general problem domain but not familiar with your specific work. This includes yourself in 2 years time.

This seems rather like the question of readability for scientific writing. Research papers should be readable to other researchers in the field, but they aren't generally expected to be readable to a general audience.

[0] https://en.wikipedia.org/wiki/No_Silver_Bullet#Summary

+1, to come back to the author's own narrative, familiarity plays a big role here.

If the new engineer is well versed in mapping and filtering he/she'll have an easier time onboarding a codebase that's rather void of manual loops.

It is hardly worth bothering how readable is "local code".

Following the same patterns across large parts of the codebase is what makes the codebase as a whole readable. Those patterns may even be complex, as long as they are used over and over without too much deviation and flag-explosion the codebase will be readable.

In short local isolated code can be as bad to read as it wants, as long as it doesn't infect the codebase as a whole (like through the use of shared mutable state or through a bad API).

Completely agree. Readability is actually in the word itself read + ability. The ability of both the code and the reader.

Code readability isn't a metric. It is a tradeoff. It basically boils down to: if in doubt will that programmer go with the more readable version of the code or do they stick with the slightly terse, clever hack?

Call me naive, but I would presume that even a junior, once they start working at a company, should be familiar enough with a language that they know all the basic syntax, idioms etc. Still, even if they are, over-using some language features will make your code less readable (to anyone). E.g. some will prefer good ol' if/else to the notorious ternary operator and its many descendants. But that brings us back to your own personal taste...

I disagree. The ability of someone to read code doesn't grow exponentially, after a few years of experience everyone hits the same plateau. More years of experience does not mean you can understand more complex code.

That is to say, if you target "readable to the majority of engineers with 3-4 years of experience, without them getting confused" then you've hit the mark.

> after a few years of experience everyone hits the same plateau

I'm sorry this is a very naive take, I presume (I could be wrong) coming from someone with just a few years of experience.

Reply on news.ycombinator.com