Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What makes code hard to read: Visual patterns of complexity (2023)

seeinglogic.com

Post reply on HN
Print view View original

11–20 of 383 posts

Re: What makes code hard to read: Visual patterns of complexity (2023)

#11

Post by mpweiher »

LandR wrote: post #3
Pannoniae wrote: post #2

This is probably a bit of a cheap dismissal.... but I think this article misses the forest for the trees. They set a standard which they manage to meet - but do not really introspect on whether the standard is appropriate or not. All of these metrics (except variable liveness) are on a method/function level. Guess what this encourages? Splitting everything into three-line methods which makes the codebase a massive pi…

> If a method is long to read from top to bottom, the answer isn't always splitting it into 5 smaller ones, sometimes life just has inherent complexity. Yes! This. I find it much easier to parse a long function where I can scroll down it and just read it top to bottom, then having a function which calls out to lots of other functions and I'm jumping around the code base, back and forward. Just reading the long functi…

I think the issue is whether the functions that are split out are actually useful abstractions.

If they are, you should not have to jump around the code-base, you should be able to just read the invocation and know what it does, without leaving the source function.

As an example, you probably don't whip out your kernel source code when you encounter a call to write(). At least not usually. You just know what it does and can keep going.

You probably also don't look at the generated assembly code, and maybe look up the instruction reference for your favorite microprocessor when you encounter an arithmetic operator. You just assume that you know what it does, even if that may not be 100% correct in every case.

Those are good, useful abstractions.

That's what we need to strive for when we crate code.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#12

Post by usrbinenv »

jt2190 wrote: post #8

Kudos to seeinglogic for trying to quantify that “readablity” is. We need a lot more of this. (I feel like the most common definition of readability in use today is “readable to me“.) I have a half-baked thought that we could find the actual dimensions of readability if we gave a test to a very large group of people and asked them to pick a sentence that describes what the code does. Each question would be timed. The…

That's very one-dimensional. It's usually easy to tell what the code does, but what's hard is to modify or add functionality to it. And this is because of various levels of abstractions that hide how things are interconnected.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#13

Post by usrbinenv »

usrbinenv wrote: post #12
jt2190 wrote: post #8

Kudos to seeinglogic for trying to quantify that “readablity” is. We need a lot more of this. (I feel like the most common definition of readability in use today is “readable to me“.) I have a half-baked thought that we could find the actual dimensions of readability if we gave a test to a very large group of people and asked them to pick a sentence that describes what the code does. Each question would be timed. The…

That's very one-dimensional. It's usually easy to tell what the code does, but what's hard is to modify or add functionality to it. And this is because of various levels of abstractions that hide how things are interconnected.

Another thing that comes to mind is the level at which one is familiar with a particular style of code organization & a set of abstractions. For example, Rails devs really have absolutely no problem getting up to speed with any given Rails app, but people who don't practice Ruby/Rails as their primary language/framework often complain how complicated and magical it is.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#14

Post by alpinisme »

jt2190 wrote: post #8

Kudos to seeinglogic for trying to quantify that “readablity” is. We need a lot more of this. (I feel like the most common definition of readability in use today is “readable to me“.) I have a half-baked thought that we could find the actual dimensions of readability if we gave a test to a very large group of people and asked them to pick a sentence that describes what the code does. Each question would be timed. The…

Yes one of the core challenges here is that we learn to read code. So what you learn to read and write shapes what you find readable. And lots of factors shape what you learn to read and write, including what you are trying to do, who you’re doing it with, what besides coding you knew how to do ahead of time, what other languages you know, etc. One stark possibility is that a lot of “readability” concerns after the low hanging fruit is gone (like don’t name variables with arbitrary irrelevant or misleading names) are really just about consensus building: maybe there are no right answers that transcend the particular group of programmers you are trying to work with.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#15

Post by James_K »

jt2190 wrote: post #8

Kudos to seeinglogic for trying to quantify that “readablity” is. We need a lot more of this. (I feel like the most common definition of readability in use today is “readable to me“.) I have a half-baked thought that we could find the actual dimensions of readability if we gave a test to a very large group of people and asked them to pick a sentence that describes what the code does. Each question would be timed. The…

I actually don't see any value in it. Code readability is similar to language readability in that it is mostly a concern for people who don't know a language and can be addressed by spending time with it. The real issue of programming is code complexity which you cannot determine from metrics about individual pieces of code. The problem exists in the relationships between functions rather than the implementation decisions in the bodies of those functions.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#16

Post by rudasn »

_dark_matter_ wrote: post #5
LandR wrote: post #3

Earlier quoted context omitted.

> If a method is long to read from top to bottom, the answer isn't always splitting it into 5 smaller ones, sometimes life just has inherent complexity. Yes! This. I find it much easier to parse a long function where I can scroll down it and just read it top to bottom, then having a function which calls out to lots of other functions and I'm jumping around the code base, back and forward. Just reading the long functi…

100%. Worst is when the called function is in a separate file, and the most upsetting is when it's the _only_ function in the file. I really wish IDEs or tools like Sourcegraph could handle this better.

What are talking about?! That's my favourite part when reading code! :P

Re: What makes code hard to read: Visual patterns of complexity (2023)

#17

Post by BorgHunter »

I think things like Halstead complexity or cyclomatic complexity are more heuristic than law. To read code, the most important thing to me is the abstractions that are built, and how effectively they bury irrelevant complexities and convey important concepts.

As an example, I recently refactored some Java code that was calling a service that returned a list of Things, but it was paged: You might have to make multiple calls to the service to get all the Things back. The original code used a while loop to build a list, and later in the same function did some business logic on the Things. My refactoring actually made things more complex: I created a class called a Spliterator that iterated through each page, and when it was exhausted, called the service again to get the next one. The upside was, this allowed me to simply put the Things in a Stream and, crucially, buried the paged nature of the request one level deeper. My reasoning is that separating an implementation detail (the request being paged) from the business logic makes the code easier to read, even if static code analysis would rate the code as slightly more complex. Also, the code that handles the pages is fairly robust and probably doesn't need to be the focus of developer attention very often, if ever, while the code that handles the business logic is much more likely to need changes from time to time.

As programmers, we have to deal with a very long chain of abstractions, from CPU instructions to network calls to high-falutin' language concepts all the way up to whatever business logic we're trying to implement. Along the way, we build our own abstractions. We have to take care that the abstractions we build benefit our future selves. Complexity measures can help measure this, but we have to remember that these measures are subordinate to the actual goal of code, which is communicating a complex series of rules and instructions to two very different audiences: The compiler/interpreter/VM/whatever, and our fellow programmers (often, our future selves who have forgotten half of the details about this code). We have to build high-quality abstractions to meet the needs of those two audiences, but static code analysis is only part of the puzzle.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#18

Post by esafak »

usrbinenv wrote: post #12
jt2190 wrote: post #8

Kudos to seeinglogic for trying to quantify that “readablity” is. We need a lot more of this. (I feel like the most common definition of readability in use today is “readable to me“.) I have a half-baked thought that we could find the actual dimensions of readability if we gave a test to a very large group of people and asked them to pick a sentence that describes what the code does. Each question would be timed. The…

That's very one-dimensional. It's usually easy to tell what the code does, but what's hard is to modify or add functionality to it. And this is because of various levels of abstractions that hide how things are interconnected.

Poor abstractions. Good abstractions make it easier to change things, by decomposing the code into cohesive pieces with low coupling so that you can swap them out and having to think about the surrounding pieces beyond their interfaces. A good interface is small and logical.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#19

Post by jabiko »

dijksterhuis wrote: post #7
LandR wrote: post #3

Earlier quoted context omitted.

> If a method is long to read from top to bottom, the answer isn't always splitting it into 5 smaller ones, sometimes life just has inherent complexity. Yes! This. I find it much easier to parse a long function where I can scroll down it and just read it top to bottom, then having a function which calls out to lots of other functions and I'm jumping around the code base, back and forward. Just reading the long functi…

> [than] having a function which calls out to lots of other functions and I'm jumping around the code base, back and forward. i agree with longer functions and less jumping around, but there's also some nuance i find. I sometimes find converting a complicated multi-line condition into something like the below is much easier for me to read, so long as the function is named in a clear way and the function definition is…

I think you are making a good point but if this function is only used in one place I would personally prefer to just use a variable:

    something_is_valid = something > 0 and something != foo and something > bar

    if something_is_valid:
        # do stuff
That way you can document the intention of the condition using the variable name while at the same time keeping the locality of the check.

Re: What makes code hard to read: Visual patterns of complexity (2023)

#20

Post by cardanome »

Pannoniae wrote: post #2

This is probably a bit of a cheap dismissal.... but I think this article misses the forest for the trees. They set a standard which they manage to meet - but do not really introspect on whether the standard is appropriate or not. All of these metrics (except variable liveness) are on a method/function level. Guess what this encourages? Splitting everything into three-line methods which makes the codebase a massive pi…

While I think that there is no harm in longer functions as long as the code is linear, I think the the problem is that people abstract the wrong way.

The main issue I see is people writing functions that call functions that call functions. No. Don't. Have one main function that is in control and that calls all the sub-functions. Sub-functions do not call functions on their same level, ever. Yes, those sub-function could have their own helper function and so on but the flow always needs to be clearly one-directional. Don't go across and create a spaghetti mess. Trees not graphs.

Keep your code structure as flat as possible.

> massive pile of lasagna full of global or shared state.

Yeah, the skill is to avoid shared state as much as possible. Handling state centrally and opting for pure functions as much as possible.

Post reply on HN