4 ms·

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

by mojuba 1y ago

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

zx8080 1y ago
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.
- deleted 1y ago
  [deleted]
- mojuba 1y ago
  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.
  - atoav 1y ago
    Sure, but we do agree that Hello World is MORE¹ readable in Python compared to the equivalent program in say Brainfuck? print("Hello World") vs ++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++. ¹: more readable means easier/faster to read for most human beings that know the language
  - eithed 1y ago
    I can't reasonably read whether this comment agrees or disagrees with the parent
  - deleted 1y ago
    [deleted]
  - RHSeeger 1y ago
    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.
- epolanski 1y ago
  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.
- Yoric 1y ago
  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.
  - skydhash 1y ago
    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.
    - Yoric 1y ago
      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.
ibash 1y ago
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.
- mojuba 1y ago
  > 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.
djmips 1y ago
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.
epolanski 1y ago
+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.
pjaoko 1y ago
Completely agree. Readability is actually in the word itself read + ability. The ability of both the code and the reader.
rob74 1y ago
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...
pbalcer 1y ago
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?
- PickledChris 1y ago
  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 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.
  - kaffekaka 1y ago
    Did someone claim readability does not exist?
    - hhjinks 1y ago
      > Readability is a non-concept really Yes.
      - mojuba 1y ago
        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.
        virgilp 1y ago
        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).
atoav 1y ago
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?
DanielHB 1y ago
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).
MaxBarraclough 1y ago
> 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 https://en.wikipedia.org/wiki/No_Silver_Bullet#Summary

by mojuba 1y ago

zx8080 1y ago

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.

deleted 1y ago
[deleted]
mojuba 1y ago
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.
- atoav 1y ago
  Sure, but we do agree that Hello World is MORE¹ readable in Python compared to the equivalent program in say Brainfuck? print("Hello World") vs ++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++. ¹: more readable means easier/faster to read for most human beings that know the language
- eithed 1y ago
  I can't reasonably read whether this comment agrees or disagrees with the parent
- deleted 1y ago
  [deleted]
- RHSeeger 1y ago
  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.
epolanski 1y ago
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.
Yoric 1y ago
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.
- skydhash 1y ago
  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.
  - Yoric 1y ago
    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.

ibash 1y ago

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.

mojuba 1y ago
> 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.

djmips 1y ago

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.

epolanski 1y ago

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

pjaoko 1y ago

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

rob74 1y ago

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

pbalcer 1y ago

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?

PickledChris 1y ago
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 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.
- kaffekaka 1y ago
  Did someone claim readability does not exist?
  - hhjinks 1y ago
    > Readability is a non-concept really Yes.
    - mojuba 1y ago
      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.
      - virgilp 1y ago
        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).

atoav 1y ago

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?

DanielHB 1y ago

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

MaxBarraclough 1y ago

> 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 https://en.wikipedia.org/wiki/No_Silver_Bullet#Summary