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

51–60 of 383 posts

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

#51

Post by intrasight »

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.

> Doesn't matter how it looks.

That's the mindset that the author is trying to counter.

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

#52

Post by WillAdams »

donatj wrote: post #48
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

Try searching for "literate programming" --- it should be the top link.

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

#53

Post by bluefirebrand »

CharlieDigital wrote: post #35

Maybe it's just me, but TypeScript makes code hard to read. It's fine if the data model is kept somewhat "atomic" and devs are diligent about actually declaring and documenting types (on my own projects, I'm super diligent about this). But once types start deriving from types using utility functions and then devs slack and fall back to type inference (because they skip an explicit type), it really starts to unravel b…

I agree that functions should probably specify their output type, MOSTLY to enforce that all paths that return from that function must adhere to that type

I've seen plenty of regressions where someone added a new condition to a function and then returned a slightly different type than other branches did, and it broke things

However, I don't think there is much value in putting types on variable declarations

In your example,

`const checkedDoggos = checkDogs([])` is good. Just let checkedDoggos inherit the type from the function

I have a codebase I'm working on where the linter enforces

`const checkedDoggos: DogBreedAndSize[] = checkDogs([])`

It is very silly and doesn't add much value imo

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

#54

Post by louthy »

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 100% agree with this. One of the best compliments I ever got (regarding programming) was from one of my principal engineers who said something along the lines of "your code reads like a story". He meant he could open a code file I had written, read from top to bottom and follow the 'narrative' in an easy way, because of how I'd ordered functions, but also how I created declarative implementations that would 'talk' to the reader.

I follow the pure functional programming paradigm which I think lends itself to this more narrative style. The functions are self contained in that their dependencies/inputs are the arguments provided or other pure functions, and the outputs are entirely in the return type.

This makes it incredibly easy to walk a reader through the complexity step-by-step (whereas other paradigms might have other complexities, like hidden state, for example). So, ironically, the most mathematically precise programming paradigm is also the best for the more narrative style (IMHO of course!)

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

#55

Post by ajross »

zwnow wrote: post #41
ajross wrote: post #38

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

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

It really doesn't though. Here's a function of mine. It's maybe 40 lines of logic, so medium-scale. It's part of an intrusive red/black tree implementation for Zephyr. I'm fairly proud of how it turned out, and think that this code is awfully readable given its constraints.

No human being is going to understand fix_extra_red() without having already read and understood the rest of the file, and coming to it with an understanding of the underlying algorithm. Certainly I can't. I can't even get started on maintaining this code that I originally wrote within a five minute time frame, it's an hour at least every time, just to remind myself how it works:

https://github.com/zephyrproject-rtos/zephyr/blob/main/lib/u...

Now maybe this is "bad code", and "good code" could exist for this problem that still meets your requirements. But... if so that's an awfully celestial definition if it's so hard to find.

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

#56

Post by WillAdams »

Chris_Newton wrote: post #36
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 --…

I find Literate Programming interesting partly because it’s almost the opposite of the much-advocated “many small functions” style. You could literally be writing a book that explains your program, and the code becomes almost secondary material to illustrate the main text rather than the main asset itself. I did once write a moderately substantial application as a literate Haskell program. I found that the pros and c…

The Axiom computer algebra folks seem to manage well --- I'm pretty sure that's the largest publicly available literate program which is available for inspection.

I've been working to maintain a list of Literate Programs which have been published (as well as books about the process):

https://www.goodreads.com/review/list/21394355-william-adams...

I'd be glad of any I missed, or other links to literate programs.

The list of projects so tagged on Github may be of interest:

https://github.com/topics/literate-programming

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

#57

Post by evnp »

bluGill wrote: post #21

Towards the end he had an example of splitting a sequence of "graph.nodes(`node[name = ${name}]`).connected().nodes().not('.hidden').data('name');" adding variable between some of the . in there and claimed it was marginally less efficient. This is sometimes true, but if it ever is you need to talk to your tool vendors about a better optimizes. If you are working in a language without an optimizer than the marginal d…

I found this example troubling because once all the line noise is added,

first-op second-op third-op

fourth-op fifth-op sixth-op

feels so much more impenetrable than

- first-op

- second-op

- third-op

- fourth-op

- fifth-op

- sixth-op

The point of functional styles isn't purely brevity (as implied by the commentary around this example), it also puts a focus on the clear sequence of operations and helps reduce "operators and operands" beneficially as discussed early in the post. In general I found the post oddly dismissive of these styles, instead of weighing tradeoffs as I would hope.

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

#59

Post by satisfice »

Interesting how important mere opinion seems to be, because the author doesn't seem to mention two issues that matter a great deal to me:

- Alignment of braces and brackets, instead of an opening brace at the end of one line and the closing brace at the beginning of a subsequent line. - everything I need to see is within an eyespan, instead having to jump to several different files to trace code.

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

#60

Post by stared »

snitzr wrote: post #58

Shoutout to the pipe operator in R. The code equivalent of "and then." It helps to unnest functions and put each action on one line. I know R is more for stats and data, but I just think it's neat.

Yes, dplyr pipes are wonderful.

Also, for the same reason, I find JavaScript list comprehensions cleaner than those in Python - as in the former it is possible to chain maps and filters.

Also, now there is a new pipe syntax in SQL, that adds a lot to readability.

Post reply on HN