What does code readability mean? • Hacker News Board

Re: What does code readability mean?

#51

Post by geokon » Mon, Jan 08, 2018, 3:40 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.

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

Re: What does code readability mean?

#52

Post by jasonmaydie » Mon, Jan 08, 2018, 3:44 PM UTC

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

Re: What does code readability mean?

#53

Post by catpolice » Mon, Jan 08, 2018, 3:44 PM UTC

There's a sense of "unreadable" that I sometimes use that means "the code does not contain the information that you need to understand how it will typically function". E.g. things that have internal control flow determined by complex input processing where the input is ill-specified. It can be essentially impossible to put together a mental picture of the operation of the program, because key parts are essentially unspecified.

And there's a related sense that I occasionally use to describe code that's so difficult to follow (in the sense that the control flow or structure is needless obfuscated) that the process of trying to understand it doesn't really resemble simply "reading".

Some examples:

A function is called in many places in es6 code. I want to see its definition, my editor can't figure it out. I look at the import statement, it's imported from a file. I open that file, and all it does is export * from a dozen other files - so now all I know is that it's in one of these dozen files. I am reduced to doing something like grepping for the function name and looking for the case that looks more like a definition than a call. At one point I was reading the code, now I'm doing something related and more involved than just reading.

Or, in this system components emit message objects with a "title" field. The messages are dispatched to dozens of functions across files that inspect the title field to determine if they do anything with it. Only they don't just do a simple comparison against a string literal, they check if the title meets a regex. There are many of these different regexes. I read the code that emits the message and I want to know what behaviors the message being sent out triggers - how do I track that down? I can't even grep for the message title. In order to make a list of things this message might do, I have to look through everything that might possibly handle the message and try to figure out which regexes are triggered.

In this case, reading is involved in the same way that reading through a math book and solving the exercises does involve reading - that's not where most of the work comes from.

Re: What does code readability mean?

#54

Post by tjwii » Mon, Jan 08, 2018, 3:45 PM UTC

Readablility is definitely not similar to understanding. The problem I have with reading code from other codebases is not understanding the coherence. Naming of variables is a great deal here, one poorly chosen name can totally confuse me. And still it is highly subjective because an other developer might instantly see the relation just by chance.

If you're unfortunate enough to code full-stack web apps then you'll likely be dealing with hundreds of npm libraries you've never heard of! How can you know all possible effects and side effects of 1 simple call to a method in some library? That alone would be a quite a study in some/most cases.

It would be great if for any project you can find at least an overview and explanation of the coherence that the files and used modules have in relation to each other. But unfortunately that is often missing already to start with, so you end up with a vast and often unsolvable puzzle.

Programming computers is still in its infancy. We definitely need better tools and structures to understand what's going on IMHO. It makes me laugh when people tell me they solve this with a linter.

Re: What does code readability mean?

#55

Post by tboyd47 » Mon, Jan 08, 2018, 3:48 PM UTC

dahart wrote: post #39

ebiester wrote: post #13

Earlier quoted context omitted.

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 f…

I've seen smart people fall into the following trap:

1. Previous developers did X and X is bad, therefore, their code needs to be rewritten without doing X.

2. Oh crap - turns out, the new code has all these requirements to match the old code's functionality in ways we didn't expect (letters A-W).

3. Okay, so we're doing Y and Z in the rewrite, knowing it's pretty bad, because we didn't know we'd have to do A-W and now we're short on time. Oh, and parts of the code still do X.

Now, wait a year for one third of the team to leave because they're rushed, overworked, burnt out, going in a different direction... and another third to get laid off because the project went way over time and budget...

4. Previous developers did X, Y, and Z, and X, Y, and Z are bad, therefore, their code must be rewritten...

Re: What does code readability mean?

#56

Post by oj-lappi » Mon, Jan 08, 2018, 3:48 PM UTC

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…

Read again, he says "after completion", not "before implementation".

Re: What does code readability mean?

#57

Post by chriswarbo » Mon, Jan 08, 2018, 3:50 PM UTC

kstrauser wrote: post #36

virgilp wrote: post #34

Earlier quoted context omitted.

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.

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, timezones, distributed systems, etc.)

Re: What does code readability mean?

#58

Post by arkh » Mon, Jan 08, 2018, 3:53 PM UTC

Doing a lot of code maintenance what is the worst is most "smart" things. Every time I get to some indirection to be smart and I can't just ctrl-click on some line to get to the definition I'm angry.

I don't want to check what is there at runtime once the configuration has been loaded. I don't like going through 10 get("serviceName")->handleSomething() and having to check where those services are defined. I really don't like having to go through 20 abstractions trying to find who fucked some data on the way in my debugger.

I know, your 3 loc per method codebase felt good to write. The added useless junk around the code (function definition and {} on their line) means even with a 4k monitor I can't see your full algo in one page.

Using reflection magic? Please don't. I like dumb code which shows what it does and can easily be followed.

And that's coming from someone who likes the ${whatever returns a string} method of defining dynamically named variables in php: it feels always fun to write. But it is a hindrance when debugging. And when debugging the less "small shit" you have to deal with, the more brainpower you have to focus on finding the problem.

Re: What does code readability mean?

#59

Post by crdoconnor » Mon, Jan 08, 2018, 3:54 PM UTC

geokon wrote: post #51

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.

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.

Re: What does code readability mean?

#60

Post by pluma » Mon, Jan 08, 2018, 4:00 PM UTC

pjc50 wrote: post #26

olavk wrote: post #19

Earlier quoted context omitted.

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

"Unreadable" in this whole discussion should be taken as meaning "requires effort that the reader is not willing to expend", not an absolute. There are very few things that are impossible to read at all, even the notoriously and deliberately unintelligible stunt languages like INTERCAL and brainf k.

I'd even go so far to say that the only way something can be literally unreadable is if it is physically impossible to do so (e.g. unrecoverable data) or there is not yet any known way of determining the meaning of a given text (e.g. the Voynich manuscript).

But of course that isn't what is meant when we say something is unreadable because humans don't deal in absolutes (though programmers sometimes do, which is why programmers are so fond of using overly noncommital language like "should" and "most likely").