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

41–50 of 383 posts

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

#41

Post by zwnow »

ajross wrote: post #38
zwnow wrote: post #28

Earlier quoted context omitted.

I consider code bad if it takes more then 5 seconds to read and understand the high level goal of a function. Doesn't matter how it looks. If its not possible to understand what a function accomplishes within a reasonable amount of time (without requiring hours upon hours of development experience), it's simply bad.

> I consider code bad if it takes more then 5 seconds to read and understand the high level goal of a function. That's something that's possible only for fairly trivial logic, though. Real code needs to be built on an internal "language" reflecting its invariants and data model and that's not something you can see with a microscope. IMHO obsessive attention to microscope qualities (endless style nitpicking in code re…

I even wrote no matter how it looks?

I meant the goal of your function needs to be grasped within a reasonable amount of time. This works for every codebase.

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

#42

Post by zwnow »

jacobr1 wrote: post #39
zwnow wrote: post #28

Earlier quoted context omitted.

I consider code bad if it takes more then 5 seconds to read and understand the high level goal of a function. Doesn't matter how it looks. If its not possible to understand what a function accomplishes within a reasonable amount of time (without requiring hours upon hours of development experience), it's simply bad.

There is a call-stack depth problem here that is specific to codebases though. For one familiar with the the conventions, key data abstractions (not just data model but convention of how models are structured and relate) and key code abstractions, a well formed function is easy to understand. But someone relatively new to the codebase will need to take a bunch of time switching between levels to know what can be assu…

But who talked about bad architecture? Good readable code doesn't rule out good architecture. Surely some things are complicated but even then, a dev should be able to quickly see whats going on with minimal expertise in a codebase.

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

#43

Post by fs_software »

This came up at work the other day re: client-side code readability.

In one camp, folks were in favor of component extraction/isolation with self-documenting tests wherever possible.

In the other camp, folks argued that drilling into a multi-file component tree makes the system harder to understand. They favor "locality of behavior".

Our consensus - there needs to be a balance.

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

#44

Post by klabb3 »

mrkeen wrote: post #33

The article's good, but misses my most mentally-fatiguing issue when reading code: mutability. It is such a gift to be able to "lock in" a variable's meaning exactly once while reading a given method, and to hold it constant while reasoning about the rest of the method. Your understanding of the method should monotonically increase from 0% to 100%, without needing to mentally "restart" the method because you messed u…

> This is the real reason why GOTOs are harmful: I don't have a hard time moving my mind's instruction-pointer around a method; I have a hard time knowing the state of mutable variables when GOTOs are in play.

Well, total complexity is not only about moving the instruction pointer given a known starting point. Look at it from the callee’s pov instead of the call site. If someone can jump to a line, you can’t backtrack and see what happened before, because it could have come from anywhere. Ie you needed global program analysis, instead of local.

If mutability were the true source of goto complexity then if-statements and for loops have the same issue. While I agree mutability and state directly causes complexity, I think goto was in a completely different (and harmful) category.

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

#45

Post by rob74 »

fs_software wrote: post #43

This came up at work the other day re: client-side code readability. In one camp, folks were in favor of component extraction/isolation with self-documenting tests wherever possible. In the other camp, folks argued that drilling into a multi-file component tree makes the system harder to understand. They favor "locality of behavior". Our consensus - there needs to be a balance.

Those were exactly my thoughts while reading this article: if your codebase (over)uses inheritance, interfaces, traits, facades, dependency injection etc. etc. to thinly spread any given functionality over several files, no amount of formatting or nice naming is going to save you...

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

#46

Post by User23 »

recursivedoubts wrote: post #25

There is a (large, I believe) aspect of good code that is fundamentally qualitative & almost literary. This annoys a lot of computer programmers (and academics) who are inclined to the mathematical mindset and want quantitative answers instead. I love dostoyevsky and wodehouse, both wrote very well, but also very differently. While I don't think coding is quite that open a playing field, I have worked on good code ba…

Mathematicians have recognized the importance of elegance for millennia.

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

#47

Post by mannykannot »

crazygringo wrote: post #37
mannykannot wrote: post #31

I would like to add something to the point made here: "For long function chains or callbacks that stack up, breaking up the chain into smaller groups and using a well-named variable or helper function can go a long way in reducing the cognitive load for readers. [my emphasis] // which is easier and faster to read? function funcA(graph) { return graph.nodes(`node[name = ${name}]`) .connected() .nodes() .not('.hidden')…

I'm almost always a fan of more rather than less commenting and self-documentation... ...but in this example I find the first to be far faster and easier to read. The "labeled" versions don't add any information that isn't obvious from the function names in the first. If you were giving business logic names rather than generic names (e.g. "msgRecipient", "recipientFriends", "visibleFriends" then I could see more valu…

You are right, using comments is even more effective in going from the generic to the specific - but then, there's a vocal minority who insist that comments are not only unnecessary, but a clear indication that you are doing it wrong. I must admit that I doubt many of them would endorse the use of auxiliary consts in the manner of the original example, either.

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

#48

Post by donatj »

WillAdams wrote: post #24

Why not apply a programming methodology which allows one to leverage a rich set of tools which were created for making text more readable and visually pleasing? http://literateprogramming.com/ For a book-length discussion of this see: https://www.goodreads.com/book/show/39996759-a-philosophy-of... previously discussed here at: https://news.ycombinator.com/item?id=27686818 (and other times in a more passing mention --…

Your link for literate programming just gets me a Parallels H-Sphere error

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

#49

Post by sunrunner »

zwnow wrote: post #28
recursivedoubts wrote: post #25

There is a (large, I believe) aspect of good code that is fundamentally qualitative & almost literary. This annoys a lot of computer programmers (and academics) who are inclined to the mathematical mindset and want quantitative answers instead. I love dostoyevsky and wodehouse, both wrote very well, but also very differently. While I don't think coding is quite that open a playing field, I have worked on good code ba…

I consider code bad if it takes more then 5 seconds to read and understand the high level goal of a function. Doesn't matter how it looks. If its not possible to understand what a function accomplishes within a reasonable amount of time (without requiring hours upon hours of development experience), it's simply bad.

Does this apply to all domains and all 'kinds' of code?

I feel like there's a fundamental difference in the information density between code that, for example, defines some kind of data structure (introducing a new 'shape' of data into an application) versus code that implements a known algorithm that might appear short in line length but carries a lot of information and therefore complexity.

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

#50

Post by andybp85 »

zwnow wrote: post #28
recursivedoubts wrote: post #25

There is a (large, I believe) aspect of good code that is fundamentally qualitative & almost literary. This annoys a lot of computer programmers (and academics) who are inclined to the mathematical mindset and want quantitative answers instead. I love dostoyevsky and wodehouse, both wrote very well, but also very differently. While I don't think coding is quite that open a playing field, I have worked on good code ba…

I consider code bad if it takes more then 5 seconds to read and understand the high level goal of a function. Doesn't matter how it looks. If its not possible to understand what a function accomplishes within a reasonable amount of time (without requiring hours upon hours of development experience), it's simply bad.

for the codebase i work on, i made a rule that "functions do what the name says and nothing else". this way if the function does too much, hopefully you feel dumb typing it and realize you should break it up.
Post reply on HN