Used to have a setup where, during development, I write all my .js files as "script files" rather than modules, all placed inside a folder, and the "build-step" is simply concatenating all .js files in that folder. All the functions in each script file are globally visible from all the other script files and there's no need to import/export anything. No one should publish code in that form, but during development it was incredibly freeing and helps me concentrate on the actual programming tasks at hand rather than getting sidetracked by trying to figure out the right way to organize the code into modules, something that (imo) I'm in a much better position to do when the programming tasks have largely been solved.

It's like writing a book. The natural process is to first create substantive content in fragments and then gradually for a chapter or section structure to naturally emerge from these fragmentary bits of content. Focusing too much on 'modules' during early development is imo akin to being preoccupied with spending time deciding what chapters and sections you want your book to have before even having a substantial base of content.

Unfortunately the current tooling for JS doesn't really support this workflow as well as I'd like.

Really? I've observed the opposite.

The developers that I work with that make heavy use of things like fuzzy file matching, go to definition, etc tend to have a _much_ harder time understanding the codebase.

My theory as to why this is the case is that they're never building or taking advantage of any higher level context. Having to browser through the directory structure (assuming it roughly mirrors the code structure), having to look through classes, etc forces you to actually build some awareness of the greater context of that method you're looking at.

Using "go to definition", you may find yourself in a method, then later you hit "go to definition" and find yourself in another method, and unless you've made a conscious effort to observe so, you may very likely have never noticed they're even in the same class and presumably related.

Using "go to definition" you might end up in a "process" method. Knowing that's in the "Image" class in the "ImageResizer" module would probably add a lot of clarity to what that's doing before you even get started looking at code.

When I need to onboard in a new codebase, I very much _don't_ use those tools until I have a solid grasp on the big picture.

I've used this occasionally in Emacs Lisp code and it's pretty nice, but I've never done it in other languages because I suspect that non-Emacs-users won't be able to handle it :P

The Emacs Wiki has a whole page on this: https://www.emacswiki.org/emacs/PageBreaks

A (successful!) ex-colleague of mine read thousands of lines long files top to bottom.

I don't know how, but somehow this worked for them.

The problem I've seen with this idea is that in order for it to work, you have to be willing to add more metadata to your program, because programs themselves don't have the necessary data in them. You can make it mandatory to your language, but than just raises the friction for people trying to use that language.

But, if you're willing to add the metadata to a hypothetical new system for slicing and dicing code, why aren't you using the existing mechanisms in your system for organizing and documenting things?

If you are, then you make the delta between "it may not be perfect but here's some documented and organized code" and the perfect vision small enough to not be worth a lot of effort to chase.

If you aren't, then you aren't going to give the perfect all-singing slicer and dicer what it needs either.

Replace "you" with "coworker(s)" for the same dilemma, only sadder. And your generic strawman coworkers are going to be very upset when you try to get them to use this language... "it's so hard, it's always complaining about perfectly good code, I'm missing my deadlines because it's making me document things I'll never use, I'm just putting 'a' as the documentation for these things anyhow, oh look here's our boss ordering us to go back to our previous language because we're all spending too much time documenting rather than building new features".

Some things can't really be fixed by process.

Based on what do you make this statement?

I don't feel like this is a problem. At least not for me :| Of course, size can make everything a problem, but for whatever projects I had to work with, organizing files was usually an entry-level problem that would normally sort itself out after a month or so.

In other words, I don't feel like this is a problem worth solving.

I agree. I'm usually opinionated about a related subject: code formatting. But I'm not too opinionated in one case, where we're using Prettier. The project is autoformatted and expects everyone else to do the same. It's so refreshing to let the computer take over sometimes, even if the end result isn't exactly what I would have typed out myself. If a piece of software could so something similar with the folders, files, and code that would be pretty great. Maybe. It seems like a much harder problem to solve than simple formatting, without introducing a bunch of bugs.

But you seem to be suggesting a different way of viewing the code, which I guess might be the way. But still underneath you'd have the spaghetti code, just sitting there not being dealt with, like a complicated Microsoft Word document.

But the friction to get something else established is so huge - all tooling would need to change ... unless perhaps one develops a way to translate between the internal format and text.

I'm wondering if the unison devs already have plans on working on a protocol like that.

It's definitely worth trying to have your code neatly organized in a way that maps to some clean conceptual model, but doing that well is going to require using every tool at your disposal—which includes ways of grouping code that don't need the sort of crisp definition and conceptual coherence of an in-language abstraction.

Sections and sub-sections seem like a reasonable way to do that with our modern, painfully limited tools. If we weren't limited by needing everything to live in plain text, I'd also reach for something like a system of tags.

2. So you have a class that has a bunch of getters and setters. Let's just assume that "generate them automatically" is not an option. You want to make it really easy to see the part of the class which is getters, and the part of the class which is setters, and then skim past that. How do you do it?

3. So you have a file that defines 3 data structures. Each data structure has a definition, a bunch of functions for parsing it, and a bunch of functions for serializing it. The author suggests that you split the file into 3 sections for the types, with subsections each for the definition, parsing, and serializing. How would you do it? Let's say the language is Rust or Typescript.

Of course it is a goal, but not always possible. You sometimes have two (or more) conflicting "relations" in the codebase. E.g.: you are dealing with taxes in various countries. Do you group by country or by kind of taxes (on sales, profits, earnings, energy, real estate...) ?

The right answer really depends on how your team is organized and how you are making changes.

In those cases, and in the cases where a single large file just makes more sense or is unavoidable (IaC/build scripts, shell/sql/migration scripts, config files, etc.), the author's methods are absolutely valuable.

In a related idea, I wonder what organizing code imports by one or more "tags" instead of import paths would be like. Probably too confusing after a while (tag systems tend to get that way), but fun to daydream about

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

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

They actually are if they're public static. Quite literally so, nested static classes are the exact same as "normal" classes but named `OuterName$InnerName.class`