Hacker News Reader

Comment by earthboundkid | Hacker News Reader

Are y’all reading files top to bottom? This is weird to me. I pretty much just follow execution using jump to definition, and I rarely read something top to bottom in a way that having sections would be helpful.

View on HN

The ML (metalanguage) family of languages like Standard ML, F# and OCaml intentionally enforce a one-way-flow where a function at the top cannot call anything below it (although there are ways to get around it).

I like this approach to organisation because it helps avoid dependency cyles. https://fsharpforfunandprofit.com/posts/cyclic-dependencies/

I once had to try and understand the entirety of a subsection by hopping between files that mutually depend on each other, which was quite confusing. UML diagrams I drew didn't help my understanding but drawing a dependency tree (the functions called that depends on no more are leaves and functions that call other functions are nodes) before I knew of this technique did help.

This does have its disadvantages though so I think it's a good default in some cases but one should be given the choice to break it when needed.

That makes the file backwards because main calls foo which calls bar, so it should be main, foo, bar; not bar, foo, main when you read it.

That order makes sense as well and it has the advantage that you will often see how the leaf functions fit into the overall picture if you see how other functions depend on them. I just prefer some linear order over the alternatives.

Within individual files I tend to create a mental index of names and purposes from top to bottom before tracing, which usually helps avoid redundant jumping or branching so deep it becomes difficult to keep track.

So thankful for Typescript/VSCode _chiefly_ for this reason. Doing this in JS before was hard, if not impossible. Now it's so much easier to follow control flow.

That said, staying on topic with the article, I think the times where I have a difficult time following along are when it's just a monolithic function or class, and especially if it has implicit behaviors via decorators or mixins.

So do you never look at a program and try to figure out everything that it does? You always just read one function at a time?

If I wanted a big picture, I would look at the docs to get the overview of the public interfaces. Once you're in the file, you're tracing execution for the most part.

maybe it’s a C thing where (without header definitions) you have to put main at bottom and anything it needs above it (same for functions that reference other functions/structs that aren’t main) to make the compiler happy?

Haha, me too! I was concerned for a second. Though, I do organize my files bottom to top with the innermost part of the execution at the top.

I honestly wish more people would try to organize their files to be read top-to-bottom, it makes it much faster to grok something new.

But of course there are lots of other factors constraining the way a file can/should be ordered, depending on language

Yes, the "inverted pyramid" concept from journalism. Most important details up top, implementation details down below.

In our (Swift) codebase, this typically translates into "publicly-consumable interface up top, private and internal functions down below".

Reply on news.ycombinator.com